001/*
002 *   Copyright 2020 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.JsonIgnoreProperties;
019import com.fasterxml.jackson.annotation.JsonInclude;
020import com.vonage.client.voice.VoiceName;
021
022/**
023 * An NCCO talk action which allows for synthesized speach to be sent to a call.
024 */
025@JsonInclude(value = JsonInclude.Include.NON_NULL)
026@JsonIgnoreProperties(ignoreUnknown = true)
027public class TalkAction implements Action {
028    private static final String ACTION = "talk";
029
030    private String text;
031    private Boolean bargeIn;
032    private Integer loop;
033    private Float level;
034    private VoiceName voiceName;
035
036    private TalkAction(Builder builder) {
037        this.text = builder.text;
038        this.bargeIn = builder.bargeIn;
039        this.loop = builder.loop;
040        this.level = builder.level;
041        this.voiceName = builder.voiceName;
042    }
043
044    @Override
045    public String getAction() {
046        return ACTION;
047    }
048
049    public String getText() {
050        return text;
051    }
052
053    public Boolean getBargeIn() {
054        return bargeIn;
055    }
056
057    public Integer getLoop() {
058        return loop;
059    }
060
061    public Float getLevel() {
062        return level;
063    }
064
065    public VoiceName getVoiceName() {
066        return voiceName;
067    }
068
069    public static Builder builder(String text) {
070        return new Builder(text);
071    }
072
073    public static class Builder {
074        private String text;
075        private Boolean bargeIn = null;
076        private Integer loop = null;
077        private Float level = null;
078        private VoiceName voiceName = null;
079
080        /**
081         * @param text A string of up to 1,500 characters (excluding SSML tags) containing the message to be
082         *             synthesized in the Call or Conversation. A single comma in text adds a short pause to the
083         *             synthesized speech. To add a longer pause a break tag needs to be used in SSML.
084         *             <p>
085         *             To use SSML tags, you must enclose the text in a speak element.
086         */
087        public Builder(String text) {
088            this.text = text;
089        }
090
091        /**
092         * @param text A string of up to 1,500 characters (excluding SSML tags) containing the message to be
093         *             synthesized in the Call or Conversation. A single comma in text adds a short pause to the
094         *             synthesized speech. To add a longer pause a break tag needs to be used in SSML.
095         *             <p>
096         *             To use SSML tags, you must enclose the text in a speak element.
097         *
098         * @return The {@link Builder} to keep building.
099         */
100        public Builder text(String text) {
101            this.text = text;
102            return this;
103        }
104
105        /**
106         * @param bargeIn Set to true so this action is terminated when the user presses a button on the keypad.
107         *                Use this feature to enable users to choose an option without having to listen to the whole
108         *                message in your Interactive Voice Response (IVR). If you set bargeIn to true the next
109         *                action in the NCCO stack must be an input action. The default value is false.
110         *
111         * @return The {@link Builder} to keep building.
112         */
113        public Builder bargeIn(Boolean bargeIn) {
114            this.bargeIn = bargeIn;
115            return this;
116        }
117
118        /**
119         * @param loop The number of times text is repeated before the Call is closed.
120         *             The default value is 1. Set to 0 to loop infinitely.
121         *
122         * @return The {@link Builder} to keep building.
123         */
124        public Builder loop(Integer loop) {
125            this.loop = loop;
126            return this;
127        }
128
129        /**
130         * @param level The volume level that the speech is played. This can be any value between -1 to 1 with 0
131         *              being the default.
132         *
133         * @return The {@link Builder} to keep building.
134         */
135        public Builder level(Float level) {
136            this.level = level;
137            return this;
138        }
139
140        /**
141         * @param voiceName The name of the voice used to deliver text. You use the voiceName that has the correct
142         *                  language, gender and accent for the message you are sending.
143         *                  <p>
144         *                  For example, the default
145         *                  voice {@link VoiceName#KIMBERLY} is a female who speaks English with an American accent (en-US).
146         *
147         * @return The {@link Builder} to keep building.
148         */
149        public Builder voiceName(VoiceName voiceName) {
150            this.voiceName = voiceName;
151            return this;
152        }
153
154        /**
155         * @return A new {@link TalkAction} object from the stored builder options.
156         */
157        public TalkAction build() {
158            return new TalkAction(this);
159        }
160    }
161}