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;
020
021import java.util.Arrays;
022import java.util.Collection;
023
024/**
025 * An NCCO conversation action which enables the ability to host conference calls.
026 */
027@JsonInclude(value = JsonInclude.Include.NON_NULL)
028@JsonIgnoreProperties(ignoreUnknown = true)
029public class ConversationAction implements Action {
030    private static final String ACTION = "conversation";
031
032    private String name;
033    private Collection<String> musicOnHoldUrl;
034    private Boolean startOnEnter;
035    private Boolean endOnExit;
036    private Boolean record;
037    private Collection<String> eventUrl;
038    private EventMethod eventMethod;
039
040    private ConversationAction(Builder builder) {
041        this.name = builder.name;
042        this.musicOnHoldUrl = builder.musicOnHoldUrl;
043        this.startOnEnter = builder.startOnEnter;
044        this.endOnExit = builder.endOnExit;
045        this.record = builder.record;
046        this.eventUrl = builder.eventUrl;
047        this.eventMethod = builder.eventMethod;
048    }
049
050    @Override
051    public String getAction() {
052        return ACTION;
053    }
054
055    public String getName() {
056        return name;
057    }
058
059    public Collection<String> getMusicOnHoldUrl() {
060        return musicOnHoldUrl;
061    }
062
063    public Boolean getStartOnEnter() {
064        return startOnEnter;
065    }
066
067    public Boolean getEndOnExit() {
068        return endOnExit;
069    }
070
071    public Boolean getRecord() {
072        return record;
073    }
074
075    public Collection<String> getEventUrl() {
076        return eventUrl;
077    }
078
079    public EventMethod getEventMethod() {
080        return eventMethod;
081    }
082
083    public static Builder builder(String name) {
084        return new Builder(name);
085    }
086
087    public static class Builder {
088        private String name;
089        private Collection<String> musicOnHoldUrl = null;
090        private Boolean startOnEnter = null;
091        private Boolean endOnExit = null;
092        private Boolean record = null;
093        private Collection<String> eventUrl = null;
094        private EventMethod eventMethod = null;
095
096        /**
097         * @param name The name of the Conversation room.
098         */
099        public Builder(String name) {
100            this.name = name;
101        }
102
103        /**
104         * @param name The name of the Conversation room.
105         *
106         * @return The {@link Builder} to keep building.
107         */
108        public Builder name(String name) {
109            this.name = name;
110            return this;
111        }
112
113        /**
114         * @param musicOnHoldUrl A URL to the mp3 file to stream to participants until the conversation starts.
115         *                       By default the conversation starts when the first person calls the virtual number
116         *                       associated with your Voice app. To stream this mp3 before the moderator joins the
117         *                       conversation, set startOnEnter to false for all users other than the moderator.
118         *
119         * @return The {@link Builder} to keep building.
120         */
121        public Builder musicOnHoldUrl(Collection<String> musicOnHoldUrl) {
122            this.musicOnHoldUrl = musicOnHoldUrl;
123            return this;
124        }
125
126        /**
127         * @param musicOnHoldUrl A URL to the mp3 file to stream to participants until the conversation starts.
128         *                       By default the conversation starts when the first person calls the virtual number
129         *                       associated with your Voice app. To stream this mp3 before the moderator joins the
130         *                       conversation, set startOnEnter to false for all users other than the moderator.
131         *
132         * @return The {@link Builder} to keep building.
133         */
134        public Builder musicOnHoldUrl(String... musicOnHoldUrl) {
135            return musicOnHoldUrl(Arrays.asList(musicOnHoldUrl));
136        }
137
138        /**
139         * @param startOnEnter The default value of true ensures that the conversation starts when this caller joins
140         *                     conversation name. Set to false for attendees in a moderated conversation.
141         *
142         * @return The {@link Builder} to keep building.
143         */
144        public Builder startOnEnter(Boolean startOnEnter) {
145            this.startOnEnter = startOnEnter;
146            return this;
147        }
148
149        /**
150         * @param endOnExit For moderated conversations, set to true in the moderator NCCO so the conversation is
151         *                  ended when the moderator hangs up. The default value of false means the conversation
152         *                  is not terminated when a caller hangs up; the conversation ends when the last caller
153         *                  hangs up.
154         *
155         * @return The {@link Builder} to keep building.
156         */
157        public Builder endOnExit(Boolean endOnExit) {
158            this.endOnExit = endOnExit;
159            return this;
160        }
161
162        /**
163         * @param record Set to true to record this conversation. For standard conversations, recordings start when one
164         *               or more attendees connects to the conversation. For moderated conversations, recordings start
165         *               when the moderator joins. That is, when an NCCO is executed for the named conversation where
166         *               startOnEnter is set to true. When the recording is terminated, the URL you download the
167         *               recording from is sent to the event URL.
168         *               <p>
169         *               By default audio is recorded in MP3 format. See the <a href="https://developer.nexmo.com/voice/voice-api/guides/recordingfile-formats">recording guide</a> for more details
170         *
171         * @return The {@link Builder} to keep building.
172         */
173        public Builder record(Boolean record) {
174            this.record = record;
175            return this;
176        }
177
178        /**
179         * @param eventUrl Set the URL to the webhook endpoint Vonage calls asynchronously on each of the
180         *                 <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flowcall-states">Call States</a>.
181         *
182         * @return The {@link Builder} to keep building.
183         */
184        public Builder eventUrl(Collection<String> eventUrl) {
185            this.eventUrl = eventUrl;
186            return this;
187        }
188
189        /**
190         * @param eventUrl Set the URL to the webhook endpoint Vonage calls asynchronously on each of the
191         *                 <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flowcall-states">Call States</a>.
192         *
193         * @return The {@link Builder} to keep building.
194         */
195        public Builder eventUrl(String... eventUrl) {
196            return eventUrl(Arrays.asList(eventUrl));
197        }
198
199        /**
200         * @param eventMethod Set the HTTP method used to make the request to eventUrl. The default value is POST.
201         *
202         * @return The {@link Builder} to keep building.
203         */
204        public Builder eventMethod(EventMethod eventMethod) {
205            this.eventMethod = eventMethod;
206            return this;
207        }
208
209        /**
210         * @return A new {@link ConversationAction} object from the stored builder options.
211         */
212        public ConversationAction build() {
213            return new ConversationAction(this);
214        }
215    }
216}