Sinch Java SDK for Voice API v2

The Sinch Java SDK allows you to quickly interact with the Voice API v2 from inside your Java applications. When using the Java SDK, the code representing requests and queries sent to and responses received from the Voice API v2 are structured similarly to those that are sent and received using the Voice API v2.

The fastest way to get started with the SDK is to check out our getting-started guides. There you'll find all the instructions necessary to download, install, set up, and start using the SDK.

Syntax

Note:

This guide describes the syntactical structure of the Java SDK for the Voice API v2, including any differences that may exist between the API itself and the SDK. For a full reference on Voice API v2 calls and responses, see the Voice API v2 Reference.

The code sample below is an example of how to use the Java SDK to make a Text to speech phone call. We've also provided an example that accomplishes the same task using the REST API.

Start.java

/**
 * Sinch Java Snippet
 *
 * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java
 *
 * <p>See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details
 */
package voice.v2.calls;

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.domains.voice.api.v2.CallsService;
import com.sinch.sdk.domains.voice.models.v2.calls.request.StartCallRequest;
import com.sinch.sdk.domains.voice.models.v2.calls.response.StartCallResponse;
import com.sinch.sdk.domains.voice.models.v2.destination.Phone;
import com.sinch.sdk.domains.voice.models.v2.svaml.calls.CallEvents;
import com.sinch.sdk.domains.voice.models.v2.svaml.calls.DialCommand;
import com.sinch.sdk.domains.voice.models.v2.svaml.calls.HangupCommand;
import com.sinch.sdk.domains.voice.models.v2.svaml.playback.MessageEvents;
import com.sinch.sdk.domains.voice.models.v2.svaml.playback.MessagesCommand;
import com.sinch.sdk.domains.voice.models.v2.svaml.playback.SayMessage;
import com.sinch.sdk.models.Configuration;
import java.util.Collections;
import java.util.logging.Logger;
import utils.Settings;

public class Start {

  private static final Logger LOGGER = Logger.getLogger(Start.class.getName());

  public static void main(String[] args) {

    String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
    String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
    String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

    // The phone number to be used as the caller ID, in E.164 format (e.g., +12025550123)
    String sinchPhoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");
    // The phone number you want to call, in E.164 format (e.g., +12025550123)
    String recipientPhoneNumber = "RECIPIENT_PHONE_NUMBER";

    Configuration configuration =
        Configuration.builder()
            .setProjectId(projectId)
            .setKeyId(keyId)
            .setKeySecret(keySecret)
            .build();

    SinchClient client = new SinchClient(configuration);

    CallsService callsService = client.voice().v2().calls();

    // Played to the recipient once the call is answered, then the call is hung up
    MessagesCommand greeting =
        MessagesCommand.builder()
            .setMessages(
                Collections.singletonList(
                    SayMessage.builder()
                        .setText("Hello, your call is now connected.")
                        .setVoiceName("Emma")
                        .build()))
            .setEvents(
                MessageEvents.builder()
                    .setOnFinish(Collections.singletonList(HangupCommand.HANGUP_COMMAND))
                    .build())
            .build();

    DialCommand dial =
        DialCommand.builder()
            .setCallName("Java_SDK_Snippet_Call")
            .setFrom(Phone.builder().setNumber(sinchPhoneNumber).build())
            .setTo(Phone.builder().setNumber(recipientPhoneNumber).build())
            .setEvents(
                CallEvents.builder().setOnAnswer(Collections.singletonList(greeting)).build())
            .build();

    StartCallRequest request =
        StartCallRequest.builder().setCommands(Collections.singletonList(dial)).build();

    LOGGER.info("Start a call to: " + recipientPhoneNumber);

    StartCallResponse response = callsService.start(request);

    LOGGER.info("Response: " + response);
  }
}

This example highlights the following required to successfully make a Voice API v2 call using the Sinch Java SDK:

Client

When using the Sinch Java SDK, you initialize communication with the Sinch backend by initializing the Java SDK's main client class. This client allows you to access the functionality of the Sinch Java SDK.

Initialization

To start using the SDK, you need to initialize the main client class and create a configuration object to connect to your Sinch account. You can find all of the credentials you need on your Sinch Build Dashboard.

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.models.Configuration;
import com.sinch.sdk.models.SMSRegion;

public class App {
    
    public static void main(String[] args) {
        SinchClient client = new SinchClient(Configuration.builder()
                                    .setProjectId("YOUR_project_id")
                                    .setKeyId("YOUR_access_key")
                                    .setKeySecret("YOUR_access_secret")
                                    .setSmsRegion(SMSRegion.US)
                                    .build());
    }
}

Note

For testing purposes on your local environment it's fine to use hardcoded values, but before deploying to production we strongly recommend using environment variables to store the credentials.

Voice v2 domain

The Sinch Java SDK organizes different functionalities in the Sinch product suite into domains. These domains are accessible through the client. For example, client.voice().v2().[endpoint_category]().[method()].

Endpoint categories

In the Sinch Java SDK, Voice API v2 endpoints are accessible through the client. The naming convention of the endpoint's representation in the SDK matches the API:

For example:

MessagesCommand greeting =
    MessagesCommand.builder()
        .setMessages(
            Collections.singletonList(
                SayMessage.builder()
                    .setText("Hello, your call is now connected.")
                    .setVoiceName("Emma")
                    .build()))
        .setEvents(
            MessageEvents.builder()
                .setOnFinish(Collections.singletonList(HangupCommand.HANGUP_COMMAND))
                .build())
        .build();

DialCommand dial =
    DialCommand.builder()
        .setCallName("Java_SDK_Snippet_Call")
        .setFrom(Phone.builder().setNumber(sinchPhoneNumber).build())
        .setTo(Phone.builder().setNumber(recipientPhoneNumber).build())
        .setEvents(
            CallEvents.builder().setOnAnswer(Collections.singletonList(greeting)).build())
        .build();

StartCallRequest request =
    StartCallRequest.builder().setCommands(Collections.singletonList(dial)).build();

Request and query parameters

Requests and queries made using the Java SDK are similar to those made using the Voice v2 API. Path parameters, request body parameters, and query parameters that are used in the API are all passed as arguments to the corresponding Java method.

For example, consider this example in which the get() method of the voice().v2().calls() class is invoked:

Call response = callsService.get(callId);


url = "https://voice.api.sinch.com/v2/projects/${projectId}/calls/${callId}"

When using the Voice API v2, callId would be included as a path parameter in the request. With the Java SDK, the callId parameter is used in an object passed as an argument in the get() method.

Responses

Response fields match the API responses. They are delivered as Java objects.