Merge release 'release-2.4.0' branch into main

CHANGELOG.md

@@ -14,6 +14,16 @@ All notable changes to the **Sinch Java SDK** are documented in this file.
 > - `[design]` — API design change
 > - `[tech]` — technical improvement
 
+---
+## v2.4.0 - 2026-10-28
+
+### Voice
+- **[feature]** V2 helpers: `Destination`, SVAML commands (`Calls`, `Amd`, `Messages`, `Recording`, `CustomEvents`, `Menu`) and `CommandsSequenceCreator`. Event handlers accept a sequence lambda
+- **[feature]** V2 helpers: `CallBehaviorHelper` for services and `SinchEventResponses` for Sinch Events
+- **[feature]** V2 helpers: `VoiceName` catalog of text-to-speech voices
+- **[feature]** V2 `setCommands(...)` accepts one or more commands
+- **[doc]** V2 snippets, `sinch-events` example and README use the helpers
+
 ---
 ## v2.3.0 - 2026-10-15
 

README.md

@@ -369,6 +369,31 @@ You can find a complete example in [examples/sinch-events](https://github.com/si
 
 The Voice API v2 needs no extra parameters, use the [common client](#client-initialization) shown above.
 
+The helpers in `com.sinch.sdk.domains.voice.models.v2.helpers` build the SVAML commands of a call, the call behavior of a service and the responses to Sinch Events. For example, to call a number, play a greeting once the call is answered, then hang up:
+
+```java
+import com.sinch.sdk.domains.voice.models.v2.calls.request.StartCallRequest;
+import com.sinch.sdk.domains.voice.models.v2.helpers.Calls;
+import com.sinch.sdk.domains.voice.models.v2.helpers.CommandsSequenceCreator;
+
+StartCallRequest request =
+    StartCallRequest.builder()
+        .setCommands(
+            CommandsSequenceCreator.create()
+                .dial("RECIPIENT_PHONE_NUMBER", dial -> dial
+                    .from("SINCH_VIRTUAL_PHONE_NUMBER")
+                    .onAnswer(answered -> answered.text(
+                        "Hello from the Sinch Java SDK!",
+                        "Emma",
+                        greeting -> greeting.onFinish(Calls.hangup()))))
+                .build())
+        .build();
+
+client.voice().v2().calls().start(request);
+```
+
+The same commands answer a Sinch Event, with `SinchEventResponses.response(...)` or, for a `call.incoming` event, `SinchEventResponses.incomingCallResponse(...)`.
+
 
 ### Your first request
 

client/src/main/com/sinch/sdk/SDK.java

@@ -3,6 +3,6 @@
 public class SDK {
 
   public static final String NAME = "Sinch Java SDK";
-  public static final String VERSION = "2.4.0-dev";
+  public static final String VERSION = "2.5.0-dev";
   public static final String AUXILIARY_FLAG = "";
 }

client/src/main/com/sinch/sdk/domains/voice/models/v2/helpers/Amd.java

@@ -0,0 +1,24 @@
+package com.sinch.sdk.domains.voice.models.v2.helpers;
+
+/**
+ * Helpers to build the Answering Machine Detection SVAML command
+ *
+ * @since 2.4
+ */
+public final class Amd {
+
+  private Amd() {}
+
+  /**
+   * Detect what answered the call: a human, a machine, a beep, or an unknown result
+   *
+   * <p>Detection runs in parallel with the next commands. Set the commands to run for each result
+   * on the returned creator.
+   *
+   * @return The creator of the <code>amd</code> command
+   * @since 2.4
+   */
+  public static AmdCreator activate() {
+    return new AmdCreator();
+  }
+}

client/src/main/com/sinch/sdk/domains/voice/models/v2/helpers/AmdCreator.java

@@ -0,0 +1,200 @@
+package com.sinch.sdk.domains.voice.models.v2.helpers;
+
+import com.sinch.sdk.domains.voice.models.v2.svaml.SvamlCommand;
+import com.sinch.sdk.domains.voice.models.v2.svaml.amd.AmdCommand;
+import com.sinch.sdk.domains.voice.models.v2.svaml.amd.AmdEvents;
+import java.util.Collection;
+import java.util.List;
+import java.util.function.Consumer;
+
+/**
+ * Fluent creator of an <code>amd</code> command, returned by {@link Amd#activate()}
+ *
+ * <p>Calling an event handler more than once appends the commands.
+ *
+ * @since 2.4
+ */
+public final class AmdCreator {
+
+  private List<SvamlCommand> onHuman;
+  private List<SvamlCommand> onMachine;
+  private List<SvamlCommand> onBeep;
+  private List<SvamlCommand> onUnknown;
+
+  AmdCreator() {}
+
+  /**
+   * Add commands to run when a human answers
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onHuman(SvamlCommand... commands) {
+    onHuman = Commands.append(onHuman, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a human answers
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onHuman(Collection<? extends SvamlCommand> commands) {
+    onHuman = Commands.append(onHuman, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a human answers
+   *
+   * @param sequence Lambda adding the commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onHuman(Consumer<CommandsSequenceCreator> sequence) {
+    onHuman = Commands.append(onHuman, sequence);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a machine answers
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onMachine(SvamlCommand... commands) {
+    onMachine = Commands.append(onMachine, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a machine answers
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onMachine(Collection<? extends SvamlCommand> commands) {
+    onMachine = Commands.append(onMachine, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a machine answers
+   *
+   * @param sequence Lambda adding the commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onMachine(Consumer<CommandsSequenceCreator> sequence) {
+    onMachine = Commands.append(onMachine, sequence);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a beep is detected
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onBeep(SvamlCommand... commands) {
+    onBeep = Commands.append(onBeep, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a beep is detected
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onBeep(Collection<? extends SvamlCommand> commands) {
+    onBeep = Commands.append(onBeep, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when a beep is detected
+   *
+   * @param sequence Lambda adding the commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onBeep(Consumer<CommandsSequenceCreator> sequence) {
+    onBeep = Commands.append(onBeep, sequence);
+    return this;
+  }
+
+  /**
+   * Add commands to run when the result is unknown
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onUnknown(SvamlCommand... commands) {
+    onUnknown = Commands.append(onUnknown, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when the result is unknown
+   *
+   * @param commands Commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onUnknown(Collection<? extends SvamlCommand> commands) {
+    onUnknown = Commands.append(onUnknown, commands);
+    return this;
+  }
+
+  /**
+   * Add commands to run when the result is unknown
+   *
+   * @param sequence Lambda adding the commands to append
+   * @return This creator
+   * @since 2.4
+   */
+  public AmdCreator onUnknown(Consumer<CommandsSequenceCreator> sequence) {
+    onUnknown = Commands.append(onUnknown, sequence);
+    return this;
+  }
+
+  /**
+   * Build the <code>amd</code> command
+   *
+   * @return The command. Its <code>events</code> are only set when a handler was given
+   * @since 2.4
+   */
+  public AmdCommand build() {
+    AmdCommand.Builder builder = AmdCommand.builder();
+    if (null != onHuman || null != onMachine || null != onBeep || null != onUnknown) {
+      builder.setEvents(buildEvents());
+    }
+    return builder.build();
+  }
+
+  private AmdEvents buildEvents() {
+    AmdEvents.Builder builder = AmdEvents.builder();
+    if (null != onHuman) {
+      builder.setOnHuman(Commands.copy(onHuman));
+    }
+    if (null != onMachine) {
+      builder.setOnMachine(Commands.copy(onMachine));
+    }
+    if (null != onBeep) {
+      builder.setOnBeep(Commands.copy(onBeep));
+    }
+    if (null != onUnknown) {
+      builder.setOnUnknown(Commands.copy(onUnknown));
+    }
+    return builder.build();
+  }
+}

client/src/main/com/sinch/sdk/domains/voice/models/v2/helpers/BaseDestination.java

@@ -0,0 +1,15 @@
+package com.sinch.sdk.domains.voice.models.v2.helpers;
+
+import com.sinch.sdk.domains.voice.models.v2.destination.CallDestination;
+import com.sinch.sdk.domains.voice.models.v2.destination.CallOrigin;
+
+/**
+ * Call endpoint built by {@link Destination#of(String)}
+ *
+ * <p>Valid as <code>to</code> ({@link CallDestination}) and <code>from</code> ({@link CallOrigin}).
+ *
+ * <p>A stream endpoint is only valid as <code>to</code>: the API rejects it as <code>from</code>.
+ *
+ * @since 2.4
+ */
+public interface BaseDestination extends CallOrigin, CallDestination {}