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 com.vonage.client.voice.EndpointType;
021
022/**
023 * Represents a phone endpoint used in a {@link ConnectAction}. See
024 * <a href=https://developer.vonage.com/voice/voice-api/ncco-reference#phone-endpoint>the documentation</a>
025 * for an example.
026 */
027public class PhoneEndpoint extends JsonableBaseObject implements Endpoint {
028    private final String number, dtmfAnswer;
029    private final OnAnswer onAnswer;
030
031    private PhoneEndpoint(Builder builder) {
032        this.number = builder.number;
033        this.dtmfAnswer = builder.dtmfAnswer;
034        this.onAnswer = (builder.onAnswerUrl != null) ? new OnAnswer(builder.onAnswerUrl, builder.onAnswerRingback) : null;
035    }
036
037    @Override
038    public String getType() {
039        return EndpointType.PHONE.toString();
040    }
041
042    /**
043     * The phone number to connect to in E.164 format.
044     *
045     * @return The phone number as a string.
046     */
047    @JsonProperty("number")
048    public String getNumber() {
049        return number;
050    }
051
052    /**
053     * Set the digits that are sent to the user as soon as the Call is answered.
054     * The * and # digits are respected. You create pauses using p. Each pause is 500ms.
055     *
056     * @return The DTMF digits as a string.
057     */
058    @JsonProperty("dtmfAnswer")
059    public String getDtmfAnswer() {
060        return dtmfAnswer;
061    }
062
063    @JsonProperty("onAnswer")
064    public OnAnswer getOnAnswer() {
065        return onAnswer;
066    }
067
068    public static Builder builder(String number) {
069        return new Builder(number);
070    }
071
072    public static class Builder {
073        private String number, dtmfAnswer, onAnswerUrl, onAnswerRingback;
074
075        Builder(String number) {
076            this.number = number;
077        }
078
079        public Builder number(String number) {
080            this.number = number;
081            return this;
082        }
083
084        public Builder dtmfAnswer(String dtmfAnswer) {
085            this.dtmfAnswer = dtmfAnswer;
086            return this;
087        }
088
089        public Builder onAnswer(String url) {
090            this.onAnswerUrl = url;
091            return this;
092        }
093
094        public Builder onAnswer(String url, String ringback) {
095            this.onAnswerUrl = url;
096            this.onAnswerRingback = ringback;
097            return this;
098        }
099
100        public PhoneEndpoint build() {
101            return new PhoneEndpoint(this);
102        }
103    }
104
105    /**
106     * An object containing a required url key. The URL serves an NCCO to execute in the number being connected to,
107     * before that call is joined to your existing conversation. Optionally, the ringbackTone key can be specified
108     * with a URL value that points to a ringbackTone to be played back on repeat to the caller, so they do not hear
109     * just silence. The ringbackTone will automatically stop playing when the call is fully connected. Please note,
110     * the key ringback is still supported.
111     */
112        public static class OnAnswer {
113        private final String url, ringback;
114
115        private OnAnswer(String url, String ringback) {
116            this.url = url;
117            this.ringback = ringback;
118        }
119
120        @JsonProperty("url")
121        public String getUrl() {
122            return url;
123        }
124
125        @JsonProperty("ringback")
126        public String getRingback() {
127            return ringback;
128        }
129    }
130}