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;
017
018import com.fasterxml.jackson.annotation.JsonAlias;
019import com.fasterxml.jackson.annotation.JsonCreator;
020import com.fasterxml.jackson.annotation.JsonProperty;
021import com.vonage.client.Jsonable;
022import com.vonage.client.JsonableBaseObject;
023import java.net.URI;
024import java.time.Instant;
025import java.util.UUID;
026
027/**
028 * Represents all call events sent to the {@code event_url} webhook configured in your Voice application settings.
029 * See <a href=https://developer.vonage.com/en/voice/voice-api/webhook-reference#event-webhook>
030 * the webhook reference</a> for details. For the {@code answer_url} webhook, use {@link AnswerWebhook}.
031 * The fields present depends on which event has occurred. This class maps all known fields for all events.
032 *
033 * @since 8.2.0
034 */
035public class EventWebhook extends JsonableBaseObject {
036    private CallStatus status;
037    private CallDirection direction;
038    private CallStatusDetail detail;
039    private MachineDetectionStatus machineDetectionSubstate;
040    private DtmfResult dtmf;
041    private SpeechResults speech;
042    private Instant timestamp, startTime, endTime;
043    private Integer duration, size;
044    private Double rate, price;
045    private URI recordingUrl;
046    private String to, from, network, reason,
047            callUuid, recordingUuid, conversationUuid, conversationUuidFrom, conversationUuidTo;
048
049    protected EventWebhook() {}
050
051    /**
052     * Event type.
053     *
054     * @return The call status as an enum.
055     */
056    @JsonProperty("status")
057    public CallStatus getStatus() {
058        return status;
059    }
060
061    /**
062     * Call direction, can be either inbound or outbound.
063     *
064     * @return The call direction as an enum, or {@code null} if not applicable.
065     */
066    @JsonProperty("direction")
067    public CallDirection getDirection() {
068        return direction;
069    }
070
071    /**
072     * Provides a more specific status to accompany {@linkplain #getStatus()}.
073     *
074     * @return The event status detail as an enum, or {@code null} if not applicable.
075     */
076    @JsonProperty("detail")
077    public CallStatusDetail getDetail() {
078        return detail;
079    }
080
081    /**
082     * Advanced machine detection status, when call is answered by voicemail and the beep is detected. This is
083     * present if {@linkplain #getStatus()} is {@linkplain CallStatus#HUMAN} or {@linkplain CallStatus#MACHINE}.
084     *
085     * @return The machine detection substate, or {@code null} if not applicable.
086     */
087    @JsonProperty("sub_state")
088    public MachineDetectionStatus getMachineDetectionSubstate() {
089        return machineDetectionSubstate;
090    }
091
092    /**
093     * DTMF capturing results.
094     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#INPUT}.
095     *
096     * @return The DTMF input, or {@code null} if not applicable.
097     */
098    @JsonProperty("dtmf")
099    public DtmfResult getDtmf() {
100        return dtmf;
101    }
102
103    /**
104     * Speech recognition results.
105     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#INPUT}.
106     *
107     * @return The speech properties, or {@code null} if not applicable.
108     */
109    @JsonProperty("speech")
110    public SpeechResults getSpeech() {
111        return speech;
112    }
113
114    /**
115     * Event timestamp in ISO 8601 format.
116     *
117     * @return The timestamp as an Instant, or {@code null} if unknown.
118     */
119    @JsonProperty("timestamp")
120    public Instant getTimestamp() {
121        return timestamp;
122    }
123
124    /**
125     * Start time in ISO 8601 format. This is applicable to recording events.
126     *
127     * @return The start time as an Instant, or {@code null} if unknown / not applicable.
128     */
129    @JsonProperty("start_time")
130    public Instant getStartTime() {
131        return startTime;
132    }
133
134    /**
135     * End time in ISO 8601 format. This is applicable to recording events.
136     *
137     * @return The end time as an Instant, or {@code null} if unknown / not applicable.
138     */
139    @JsonProperty("end_time")
140    public Instant getEndTime() {
141        return endTime;
142    }
143
144    /**
145     * Call length, in seconds. This is present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
146     *
147     * @return The length of the call, or {@code null} if not applicable.
148     */
149    @JsonProperty("duration")
150    public Integer getDuration() {
151        return duration;
152    }
153
154    /**
155     * Size of the recording file, in bytes. This is present for recording events only.
156     *
157     * @return The file size in bytes, or {@code null} if not applicable.
158     */
159    @JsonProperty("size")
160    public Integer getSize() {
161        return size;
162    }
163
164    /**
165     * Cost per minute of the call, in Euros.
166     * This will be present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
167     *
168     * @return The call rate as a double, or {@code null} if not applicable.
169     */
170    @JsonProperty("rate")
171    public Double getRate() {
172        return rate;
173    }
174
175    /**
176     * Total cost of the call in Euros.
177     * This will be present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
178     *
179     * @return The call cost as a double, or {@code null} if not applicable.
180     */
181    @JsonProperty("price")
182    public Double getPrice() {
183        return price;
184    }
185
186    /**
187     * Where to download the recording. This is present for recording and transcription events only.
188     *
189     * @return The URL of the recording, or {@code null} if not applicable.
190     */
191    @JsonProperty("recording_url")
192    public URI getRecordingUrl() {
193        return recordingUrl;
194    }
195
196    /**
197     * Unique identifier for the call event.
198     *
199     * @return The call ID as a string, or {@code null} not applicable.
200     */
201    @JsonProperty("uuid")
202    @JsonAlias({"uuid", "call_uuid"})
203    public String getCallUuid() {
204        return callUuid;
205    }
206
207    /**
208     * Unique identifier for the recording. This is only present for recording events.
209     *
210     * @return The recording ID as a string, or {@code null} if not applicable.
211     */
212    @JsonProperty("recording_uuid")
213    public String getRecordingUuid() {
214        return recordingUuid;
215    }
216
217    /**
218     * Number the call was made to, in E.164 format.
219     *
220     * @return The call destination, or {@code null} if not applicable.
221     */
222    @JsonProperty("to")
223    public String getTo() {
224        return to;
225    }
226
227    /**
228     * Number the call came from, in E.164 format.
229     *
230     * @return The call source number, or {@code null} if not applicable.
231     */
232    @JsonProperty("from")
233    public String getFrom() {
234        return from;
235    }
236
237    /**
238     * Unique identifier for the conversation. Starts with {@code CON-} followed by a UUID.
239     *
240     * @return The conversation ID as a string, or {@code null} if not applicable.
241     */
242    @JsonProperty("conversation_uuid")
243    public String getConversationUuid() {
244        return conversationUuid;
245    }
246
247    /**
248     * Conversation ID that the leg was originally in.
249     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#TRANSFER}.
250     *
251     * @return The originating conversation ID leg, or {@code null} if not applicable.
252     */
253    @JsonProperty("conversation_uuid_from")
254    public String getConversationUuidFrom() {
255        return conversationUuidFrom;
256    }
257
258    /**
259     * Conversation ID that the leg was transferred to.
260     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#TRANSFER}.
261     *
262     * @return The destination conversation ID leg, or {@code null} if not applicable.
263     */
264    @JsonProperty("conversation_uuid_to")
265    public String getConversationUuidTo() {
266        return conversationUuidTo;
267    }
268
269    /**
270     * Type of network that was used in the call.
271     *
272     * @return The network, or {@code null} if unknown / not applicable.
273     */
274    @JsonProperty("network")
275    public String getNetwork() {
276        return network;
277    }
278
279    /**
280     * Information about the nature of the error. This is only present for error webhooks.
281     *
282     * @return The error description, or {@code null} if not applicable.
283     */
284    @JsonProperty("reason")
285    public String getReason() {
286        return reason;
287    }
288
289    /**
290     * Constructs an instance, populating this class's fields from the JSON string.
291     *
292     * @param json The JSON payload as a string.
293     *
294     * @return A new instance of this class.
295     */
296    @JsonCreator
297    public static EventWebhook fromJson(String json) {
298        return Jsonable.fromJson(json);
299    }
300}