Sinch Java SDK for Conversation

The Sinch Conversation Java SDK allows you to quickly interact with the Conversation API from inside your Java applications. 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

When using the Java SDK, the code representing requests and queries sent to and responses received from the Conversation API are structured similarly to those that are sent and received using the Conversation API itself.

The code sample on the side of this page is an example of how to use the Java SDK to send a text message on the SMS channel of a Conversation API app. The Conversation API call that accomplishes the same task is displayed below for reference:

// Find your App ID at dashboard.sinch.com/convapi/apps
// Find your Project ID at dashboard.sinch.com/settings/project-management
// Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys
import java.net.*;
import java.net.http.*;
import java.util.*;

public class App {
  public static void main(String[] args) throws Exception {
    var httpClient = HttpClient.newBuilder().build();

    var payload = String.join("\n"
      , "{"
      , " \"app_id\": \"{APP_ID}\","
      , " \"recipient\": {"
      , "  \"identified_by\": {"
      , "   \"channel_identities\": ["
      , "    {"
      , "     \"channel\": \"{CHANNEL}\","
      , "     \"identity\": \"{IDENTITY}\""
      , "    }"
      , "   ]"
      , "  }"
      , " },"
      , " \"message\": {"
      , "  \"text_message\": {"
      , "   \"text\": \"This is a text message.\""
      , "  }"
      , " }"
      , "}"
    );

    var host = "https://{region}.conversation.api.sinch.com";
    var projectId = "YOUR_project_id_PARAMETER";
    var region = "us";
    var pathname = "/v1/projects/%7Bproject_id%7D/messages:send";
    var request = HttpRequest.newBuilder()
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .uri(URI.create(host + pathname ))
      .header("Content-Type", "application/json")
      .header("Authorization", "Basic " + Base64.getEncoder().encodeToString(("<username>:<password>").getBytes()))
      .build();

    var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

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

• Client initialization
• Conversation domain access
• Endpoint usage
• Field population

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 successfully initialize the Sinch client class, you must provide a valid access key ID and access key secret combination. You must also provide your Project ID. For example:

package conversation.sdk;

import com.sinch.sdk.SinchClient;

public class App {
    
    public static String access_key = "YOUR_access_key";
    public static String access_secret = "YOUR_access_secret";
    public static String project_id = "YOUR_project_id"

    public static void main(String[] args) {
        
      SinchClient client = new SinchClient(Configuration.builder()
                                  .setKeyId(access_key)
                                  .setKeySecret(access_secret)
                                  .setProjectId(project_id)
                                  .build());
}

Conversation domain

Endpoint categories

In the Sinch Java SDK, Conversation API endpoints are accessible through the client (either a general client or a Conversation-specific client). The naming convention of the endpoint's representation in the SDK matches the API:

• v1().messages()
• v1().app()
• v1().contact()
• v1().events()
• v1().transcoding()
• v1().capability()
• templates.v1().templates()
• templates.v2().templates()
• v1().webhooks()
• v1().conversation()

For example:

SendMessageResponse response =
    client.conversation().v1().messages().sendMessage(SendMessageRequest.<TextMessage>builder()
        .setAppId("YOUR_app_id")
        .setRecipient(ChannelRecipientIdentities.of(ChannelRecipientIdentity.builder().setChannel(ConversationChannel.SMS).setIdentity("RECIPIENT_number").build()))
        .setMessage(AppMessage.<TextMessage>builder().setBody(TextMessage.builder().setText("This is a test Conversation message using the Sinch Java SDK.").build()).build())
        .setChannelProperties(Collections.singletonMap("SMS_SENDER", "YOUR_sms_sender"))
        .build());

conversation().v1().messages endpoint category

conversation().v1().app() endpoint category

The ConversationChannelCredentialsBuilderFactory class

conversation().v1().contact() endpoint category

conversation().v1().conversations() endpoint category

conversation().v1().events() endpoint category

conversation().v1().transcoding() endpoint category

conversation().v1().capability() endpoint category

conversation().v1().webhooks() endpoint category

conversation().templates().v1().templates() endpoint category

conversation().templates().v2().templates() endpoint category

Request and query parameters

Requests and queries made using the Java SDK are similar to those made using the Conversation API. Many of the fields are named and structured similarly. For example, consider the representation of a Conversation API channel. One field is represented in our Java SDK, and the other is using the REST API:

ConversationChannel.SMS

"     \"channel\": \"SMS\","

Note that the fields have similar names, and many fields in the Java SDK are rendered as enums in data models.

var response = client.conversation().v1().messages().get("YOUR_message_id", "CONVERSATION_SOURCE");

var host = "https://{region}.conversation.api.sinch.com";
var projectId = "YOUR_project_id_PARAMETER";
var messageId = "YOUR_message_id_PARAMETER";
var region = "us";
var pathname = "/v1/projects/%7Bproject_id%7D/messages/%7Bmessage_id%7D";
var request = HttpRequest.newBuilder()
  .GET()
  .uri(URI.create(host + pathname ))
  .header("Authorization", "Basic " + Base64.getEncoder().encodeToString(("<username>:<password>").getBytes()))
  .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

Responses

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