Add event webhook

src/main/java/com/vonage/client/incoming/CallStatusDetail.java

@@ -18,42 +18,52 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 
 public enum CallStatusDetail {
+
     /**
-     * No detail field present
+     * No detail field present.
      */
     NO_DETAIL,
+
     /**
-     * Detail present, but has not been mapped to an enum yet
+     * Detail present, but has not been mapped to an enum yet.
      */
     UNMAPPED_DETAIL,
+
     /**
-     * Number invalid
+     * Number invalid.
      */
     INVALID_NUMBER,
+
     /**
-     * Rejected by carrier
+     * Rejected by carrier.
      */
     RESTRICTED,
+
     /**
-     * Call rejected by callee
+     * Call rejected by callee.
      */
     DECLINED,
+
     /**
-     * Cannot route to the number
+     * Cannot route to the number.
      */
     CANNOT_ROUTE,
+
     /**
-     * Number is no longer available
+     * Number is no longer available.
      */
     NUMBER_OUT_OF_SERVICE,
+
     /**
-     * Server error or failure
+     * Server error or failure.
      */
     INTERNAL_ERROR,
+
     /**
-     * Carrier timed out
+     * Carrier timed out.
      */
     CARRIER_TIMEOUT,
+
     /**
      * Callee is temporarily unavailable.
      */

src/main/java/com/vonage/client/incoming/DtmfResult.java

@@ -17,24 +17,30 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.vonage.client.voice.EventWebhook;
 
+/**
+ * Represents the DTMF event results in {@link EventWebhook#getDtmf()}.
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class DtmfResult {
     private String digits;
     private boolean timedOut;
 
     /**
+     * The button sequence pressed by the user.
      *
-     * @return The buttons pressed by the user
+     * @return The buttons pressed as a String.
      */
     @JsonProperty("digits")
     public String getDigits() {
         return digits;
     }
 
     /**
+     * Whether the DTMF input timed out.
      *
-     * @return Whether the DTMF input timed out: true if it did, false if not
+     * @return {@code true} if the DTMF timed out, {@code false} otherwise.
      */
     @JsonProperty("timed_out")
     public boolean isTimedOut() {

src/main/java/com/vonage/client/incoming/Result.java

@@ -15,36 +15,55 @@
  */
 package com.vonage.client.incoming;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(value = JsonInclude.Include.NON_NULL)
 public class Result {
     private String text, confidence;
 
     /**
-     * 
-     * @return transcript text
+     * Transcript text representing the words that the user spoke.
+     *
+     * @return The transcript text.
      */
+    @JsonProperty("text")
     public String getText() {
         return text;
     }
 
     /**
      * @param text transcript text representing the words the user spoke.
+     *
+     * @deprecated This setter will be removed in a future release.
      */
+    @Deprecated
     public void setText(String text) {
         this.text = text;
     }
 
     /**
-     * 
-     * @return The confidence estimate between 0.0 and 1.0
+     * The confidence estimate between 0.0 and 1.0. A higher number indicates an estimated greater
+     * likelihood that the recognized words are correct.
+     *
+     * @return The confidence estimate between 0.0 and 1.0 as a String.
+     *
+     * @deprecated This will be converted to a Double in a future release.
      */
+    @Deprecated
     public String getConfidence() {
         return confidence;
     }
 
     /**
      * @param confidence The confidence estimate between 0.0 and 1.0. A higher number indicates an estimated greater
      *                   likelihood that the recognized words are correct.
+     *
+     * @deprecated This setter will be removed in a future release.
      */
+    @Deprecated
     public void setConfidence(String confidence) {
         this.confidence = confidence;
     }

src/main/java/com/vonage/client/incoming/SpeechResults.java

@@ -15,53 +15,101 @@
  */
 package com.vonage.client.incoming;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
-
+import com.fasterxml.jackson.annotation.JsonValue;
+import java.net.URI;
 import java.util.Collection;
 
 @JsonInclude(value = JsonInclude.Include.NON_NULL)
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class SpeechResults {
-    @JsonProperty("timeout_reason")
     private TimeoutReason timeoutReason;
     private Collection<Result> results;
     private String error;
+    private URI recordingUrl;
 
+    /**
+     * Speech recording URL. Included if the {@code saveAudio} flag is set to {@code true} in
+     * the input action. Requires JWT authorization for downloading see <a
+     * href=https://developer.vonage.com/en/voice/voice-api/code-snippets/recording-calls/download-a-recording>
+     * Download a Recording</a> documentation for details.
+     *
+     * @return The recording URL, or {@code null} if absent.
+     *
+     * @since 8.2.0
+     */
+    @JsonProperty("recording_url")
+    public URI getRecordingUrl() {
+        return recordingUrl;
+    }
+
+    /**
+     * Error message.
+     *
+     * @return The error message, or {@code null} if absent / not applicable.
+     */
+    @JsonProperty("error")
     public String getError() {
         return error;
     }
 
+    /**
+     * Indicates if the input ended when user stopped speaking, by max duration timeout
+     * or if the user didn't say anything.
+     *
+     * @return Reason for the timeout as an enum.
+     */
+    @JsonProperty("timeout_reason")
     public TimeoutReason getTimeoutReason() {
         return timeoutReason;
     }
 
     /**
      * @param timeoutReason Indicates whether the input ended when the user stopped speaking, by the max duration
-     *                      timeout, or if the user didn't say anything
+     *                      timeout, or if the user didn't say anything.
+     *
+     * @deprecated This setter will be removed in a future release.
      */
+    @Deprecated
     public void setTimeoutReason(TimeoutReason timeoutReason) {
         this.timeoutReason = timeoutReason;
     }
 
-
+    /**
+     * The recognised text objects.
+     *
+     * @return The collection of transcript texts, or {@code null} if there are none.
+     */
+    @JsonProperty("results")
     public Collection<Result> getResults() {
         return results;
     }
 
     /**
      * @param results list of speech recognition results that displays the words(s) that the user spoke and the
      *                likelihood that the recognized word(s) in the list where the actual word(s) that the user spoke.
+     *
+     * @deprecated This setter will be removed in a future release.
      */
+    @Deprecated
     public void setResults(Collection<Result> results) {
         this.results = results;
     }
 
+    /**
+     * Represents the timeout reason in {@linkplain #getTimeoutReason()}.
+     */
     public enum TimeoutReason {
-        @JsonProperty("end_on_silence_timeout")
         END_ON_SILENCE_TIMEOUT,
-        @JsonProperty("max_duration")
         MAX_DURATION,
-        @JsonProperty("start_timeout")
-        START_TIMEOUT
+        START_TIMEOUT;
+
+        @JsonValue
+        @Override
+        public String toString() {
+            return name().toLowerCase();
+        }
     }
 }

src/main/java/com/vonage/client/voice/AdvancedMachineDetection.java

@@ -18,7 +18,9 @@
 import com.fasterxml.jackson.annotation.*;
 
 /**
- * Configure the behavior of Vonage's advanced machine detection.
+ * Configure the behavior of Vonage's advanced machine detection. See
+ * <a href=https://developer.vonage.com/en/voice/voice-api/concepts/advanced-machine-detection>
+ * the documentation</a> for details.
  *
  * @since 7.4.0
  */
@@ -39,7 +41,14 @@ public enum Mode {
 		 * Detect machine and send back a status human / machine webhook, but also when machine is detected, attempt
 		 * to detect voice mail beep and send back another status machine webhook with {@code sub_state: beep_start}.
 		 */
-		DETECT_BEEP;
+		DETECT_BEEP,
+
+		/**
+		 * Asynchronously start processing NCCO actions during the detection phase.
+		 *
+		 * @since 8.2.0
+		 */
+		DEFAULT;
 
 		@JsonCreator
 		public static Mode fromString(String value) {

src/main/java/com/vonage/client/voice/CallStatus.java

@@ -18,17 +18,93 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonValue;
 
+/**
+ * Describes the status of the call, and also the event in {@link EventWebhook#getStatus()}.
+ */
 public enum CallStatus {
+
+    /**
+     * Indicates that the call has been created.
+     */
     STARTED,
+
+    /**
+     * The call is ringing.
+     */
     RINGING,
+
+    /**
+     * The call was answered.
+     */
     ANSWERED,
+
+    /**
+     * The duration of the ringing phase exceeded the specified ringing timeout duration.
+     */
     TIMEOUT,
+
+    /**
+     * For an outbound call made programmatically with machine detection enabled,
+     * this indicates a machine / voicemail answered the call.
+     */
     MACHINE,
+
+    /**
+     * The call has finished.
+     */
     COMPLETED,
+
+    /**
+     * The outgoing call could not be connected.
+     */
     FAILED,
+
+    /**
+     * The call was rejected by Vonage before it was connected.
+     */
     REJECTED,
+
+    /**
+     * The destination is on the line with another caller.
+     */
     BUSY,
+
+    /**
+     * An outgoing call is cancelled by the originator before being answered.
+     */
     CANCELLED,
+
+    /**
+     * A leg has been transferred from one conversation to another.
+     */
+    TRANSFER,
+
+    /**
+     * An NCCO {@code input} action has finished.
+     */
+    INPUT,
+
+    /**
+     * For an outbound call made programmatically with machine detection enabled,
+     * this indicates a human answered the call.
+     */
+    HUMAN,
+
+    /**
+     * If the WebSocket connection is terminated from the application side for any reason,
+     * then the disconnected event callback will be sent. If the response contains an NCCO
+     * then this will be processed, if no NCCO is present then normal execution will continue.
+     */
+    DISCONNECTED,
+
+    /**
+     * Either the recipient is unreachable or the recipient declined the call.
+     */
+    UNANSWERED,
+
+    /**
+     * Unknown status or event.
+     */
     UNKNOWN;
 
     @JsonValue