001/*
002 *   Copyright 2024 Vonage
003 *
004 *   Licensed under the Apache License, Version 2.0 (the "License");
005 *   you may not use this file except in compliance with the License.
006 *   You may obtain a copy of the License at
007 *
008 *        http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *   Unless required by applicable law or agreed to in writing, software
011 *   distributed under the License is distributed on an "AS IS" BASIS,
012 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *   See the License for the specific language governing permissions and
014 *   limitations under the License.
015 */
016package com.vonage.client.voice.ncco;
017
018import com.fasterxml.jackson.annotation.JsonProperty;
019import com.vonage.client.JsonableBaseObject;
020import java.net.URI;
021import java.util.Collections;
022import java.util.List;
023
024/**
025 * Customisable settings for call recording transcription.
026 *
027 * @since 8.2.0
028 */
029public final class TranscriptionSettings extends JsonableBaseObject {
030    private SpeechSettings.Language language;
031    private List<URI> eventUrl;
032    private EventMethod eventMethod;
033    private Boolean sentimentAnalysis;
034
035    TranscriptionSettings() {}
036
037    private TranscriptionSettings(Builder builder) {
038        language = builder.language;
039        eventMethod = builder.eventMethod;
040        sentimentAnalysis = builder.sentimentAnalysis;
041        if (builder.eventUrl != null) {
042            eventUrl = Collections.singletonList(URI.create(builder.eventUrl));
043        }
044    }
045
046    /**
047     * Language for the recording transcription.
048     *
049     * @return The language as an enum, or {@code null} if unspecified.
050     */
051    @JsonProperty("language")
052    public SpeechSettings.Language getLanguage() {
053        return language;
054    }
055
056    /**
057     * The URL to the webhook endpoint that is called asynchronously when a transcription is finished.
058     *
059     * @return The event URL wrapped in a list, or {@code null} if unspecified.
060     */
061    @JsonProperty("eventUrl")
062    public List<URI> getEventUrl() {
063        return eventUrl;
064    }
065
066    /**
067     * The HTTP method Vonage uses to make the request to {@linkplain #getEventUrl()}.
068     *
069     * @return The event method, or {@code null} if unspecified.
070     */
071    @JsonProperty("eventMethod")
072    public EventMethod getEventMethod() {
073        return eventMethod;
074    }
075
076    /**
077     * Perform sentiment analysis on the call recording transcription segments.
078     *
079     * @return Whether sentiment analysis is enabled, or {@code null} if unspecified.
080     */
081    @JsonProperty("sentimentAnalysis")
082    public Boolean getSentimentAnalysis() {
083        return sentimentAnalysis;
084    }
085
086    /**
087     * Entrypoint for constructing an instance of this class.
088     *
089     * @return A new builder.
090     */
091    public static Builder builder() {
092        return new Builder();
093    }
094
095    /**
096     * Builder for setting the TranscriptionSettings parameters. All settings / fields are optional.
097     */
098    public static final class Builder {
099        private SpeechSettings.Language language;
100        private String eventUrl;
101        private EventMethod eventMethod;
102        private Boolean sentimentAnalysis;
103
104        private Builder() {}
105
106        /**
107         * The language (BCP-47 format) for the recording you're transcribing.
108         * This currently supports the same languages as Automatic Speech Recording.
109         *
110         * @param language The recording language as an enum.
111         * @return This builder.
112         */
113        public Builder language(SpeechSettings.Language language) {
114            this.language = language;
115            return this;
116        }
117
118        /**
119         * The URL to the webhook endpoint that is called asynchronously when a transcription is finished.
120         *
121         * @param eventUrl The event URL as a string.
122         * @return This builder.
123         */
124        public Builder eventUrl(String eventUrl) {
125            this.eventUrl = eventUrl;
126            return this;
127        }
128
129        /**
130         * The HTTP method Vonage uses to make the request to {@code eventUrl}.
131         * The default value is {@link EventMethod#POST}.
132         *
133         * @param eventMethod The HTTP method as an enum.
134         * @return This builder.
135         */
136        public Builder eventMethod(EventMethod eventMethod) {
137            this.eventMethod = eventMethod;
138            return this;
139        }
140
141        /**
142         * Whether to perform sentiment analysis on the call recording transcription segments. Will return a value
143         * between -1 (negative sentiment) and 1 (positive sentiment) for each segment. Defaults to {@code false}.
144         *
145         * @param sentimentAnalysis {@code true} to enable sentiment analysis on the recording.
146         * @return This builder.
147         */
148        public Builder sentimentAnalysis(boolean sentimentAnalysis) {
149            this.sentimentAnalysis = sentimentAnalysis;
150            return this;
151        }
152
153        /**
154         * Builds the TranscriptionSettings object.
155         *
156         * @return A new TranscriptionSettings instance with this builder's settings.
157         */
158        public TranscriptionSettings build() {
159            return new TranscriptionSettings(this);
160        }
161    }
162}