001/*
002 * Copyright (c) 2011-2017 Nexmo Inc
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.nexmo.client.voice.ncco;
023
024import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
025import com.fasterxml.jackson.annotation.JsonInclude;
026
027import java.util.Arrays;
028import java.util.Collection;
029
030/**
031 * An NCCO conversation action which enables the ability to host conference calls.
032 */
033@JsonInclude(value = JsonInclude.Include.NON_NULL)
034@JsonIgnoreProperties(ignoreUnknown = true)
035public class ConversationAction implements Action {
036    private static final String ACTION = "conversation";
037
038    private String name;
039    private Collection<String> musicOnHoldUrl;
040    private Boolean startOnEnter;
041    private Boolean endOnExit;
042    private Boolean record;
043    private Collection<String> eventUrl;
044    private EventMethod eventMethod;
045
046    private ConversationAction(Builder builder) {
047        this.name = builder.name;
048        this.musicOnHoldUrl = builder.musicOnHoldUrl;
049        this.startOnEnter = builder.startOnEnter;
050        this.endOnExit = builder.endOnExit;
051        this.record = builder.record;
052        this.eventUrl = builder.eventUrl;
053        this.eventMethod = builder.eventMethod;
054    }
055
056    @Override
057    public String getAction() {
058        return ACTION;
059    }
060
061    public String getName() {
062        return name;
063    }
064
065    public Collection<String> getMusicOnHoldUrl() {
066        return musicOnHoldUrl;
067    }
068
069    public Boolean getStartOnEnter() {
070        return startOnEnter;
071    }
072
073    public Boolean getEndOnExit() {
074        return endOnExit;
075    }
076
077    public Boolean getRecord() {
078        return record;
079    }
080
081    public Collection<String> getEventUrl() {
082        return eventUrl;
083    }
084
085    public EventMethod getEventMethod() {
086        return eventMethod;
087    }
088
089    public static Builder builder(String name) {
090        return new Builder(name);
091    }
092
093    public static class Builder {
094        private String name;
095        private Collection<String> musicOnHoldUrl = null;
096        private Boolean startOnEnter = null;
097        private Boolean endOnExit = null;
098        private Boolean record = null;
099        private Collection<String> eventUrl = null;
100        private EventMethod eventMethod = null;
101
102        /**
103         * @param name The name of the Conversation room.
104         */
105        public Builder(String name) {
106            this.name = name;
107        }
108
109        /**
110         * @param name The name of the Conversation room.
111         *
112         * @return The {@link Builder} to keep building.
113         */
114        public Builder name(String name) {
115            this.name = name;
116            return this;
117        }
118
119        /**
120         * @param musicOnHoldUrl A URL to the mp3 file to stream to participants until the conversation starts.
121         *                       By default the conversation starts when the first person calls the virtual number
122         *                       associated with your Voice app. To stream this mp3 before the moderator joins the
123         *                       conversation, set startOnEnter to false for all users other than the moderator.
124         *
125         * @return The {@link Builder} to keep building.
126         */
127        public Builder musicOnHoldUrl(Collection<String> musicOnHoldUrl) {
128            this.musicOnHoldUrl = musicOnHoldUrl;
129            return this;
130        }
131
132        /**
133         * @param musicOnHoldUrl A URL to the mp3 file to stream to participants until the conversation starts.
134         *                       By default the conversation starts when the first person calls the virtual number
135         *                       associated with your Voice app. To stream this mp3 before the moderator joins the
136         *                       conversation, set startOnEnter to false for all users other than the moderator.
137         *
138         * @return The {@link Builder} to keep building.
139         */
140        public Builder musicOnHoldUrl(String... musicOnHoldUrl) {
141            return musicOnHoldUrl(Arrays.asList(musicOnHoldUrl));
142        }
143
144        /**
145         * @param startOnEnter The default value of true ensures that the conversation starts when this caller joins
146         *                     conversation name. Set to false for attendees in a moderated conversation.
147         *
148         * @return The {@link Builder} to keep building.
149         */
150        public Builder startOnEnter(Boolean startOnEnter) {
151            this.startOnEnter = startOnEnter;
152            return this;
153        }
154
155        /**
156         * @param endOnExit For moderated conversations, set to true in the moderator NCCO so the conversation is
157         *                  ended when the moderator hangs up. The default value of false means the conversation
158         *                  is not terminated when a caller hangs up; the conversation ends when the last caller
159         *                  hangs up.
160         *
161         * @return The {@link Builder} to keep building.
162         */
163        public Builder endOnExit(Boolean endOnExit) {
164            this.endOnExit = endOnExit;
165            return this;
166        }
167
168        /**
169         * @param record Set to true to record this conversation. For standard conversations, recordings start when one
170         *               or more attendees connects to the conversation. For moderated conversations, recordings start
171         *               when the moderator joins. That is, when an NCCO is executed for the named conversation where
172         *               startOnEnter is set to true. When the recording is terminated, the URL you download the
173         *               recording from is sent to the event URL.
174         *               <p>
175         *               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
176         *
177         * @return The {@link Builder} to keep building.
178         */
179        public Builder record(Boolean record) {
180            this.record = record;
181            return this;
182        }
183
184        /**
185         * @param eventUrl Set the URL to the webhook endpoint Nexmo calls asynchronously on each of the
186         *                 <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flowcall-states">Call States</a>.
187         *
188         * @return The {@link Builder} to keep building.
189         */
190        public Builder eventUrl(Collection<String> eventUrl) {
191            this.eventUrl = eventUrl;
192            return this;
193        }
194
195        /**
196         * @param eventUrl Set the URL to the webhook endpoint Nexmo calls asynchronously on each of the
197         *                 <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flowcall-states">Call States</a>.
198         *
199         * @return The {@link Builder} to keep building.
200         */
201        public Builder eventUrl(String... eventUrl) {
202            return eventUrl(Arrays.asList(eventUrl));
203        }
204
205        /**
206         * @param eventMethod Set the HTTP method used to make the request to eventUrl. The default value is POST.
207         *
208         * @return The {@link Builder} to keep building.
209         */
210        public Builder eventMethod(EventMethod eventMethod) {
211            this.eventMethod = eventMethod;
212            return this;
213        }
214
215        /**
216         * @return A new {@link ConversationAction} object from the stored builder options.
217         */
218        public ConversationAction build() {
219            return new ConversationAction(this);
220        }
221    }
222}