Sinch Java SDK for SMS

The Sinch SMS Java SDK allows you to quickly interact with the SMS 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 SMS API are structured similarly to those that are sent and received using the SMS API itself.

package send.sms;

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.domains.sms.models.BatchText;
import com.sinch.sdk.domains.sms.models.requests.SendSmsBatchTextRequest;
import com.sinch.sdk.models.Configuration;
import com.sinch.sdk.models.SMSRegion;

import java.io.IOException;
import java.util.Collections;
import java.util.logging.Logger;

public class App {
    private static final Logger LOGGER = Logger.getLogger(App.class.getName());

  public App() throws IOException {}

  public static void main(String[] args) {
    try {
      new App().run();
    } catch (Exception e) {
      LOGGER.severe(e.getMessage());
      e.printStackTrace();
    }
  }

  public void run() {

    SinchClient client = new SinchClient(Configuration.builder()
                                    .setKeyId("YOUR_access_key")
                                    .setKeySecret("YOUR_access_secret")
                                    .setProjectId("YOUR_project_id")
                                    .setSmsRegion(SMSRegion.US)
                                    .build());


    LOGGER.info("Send Text");
    BatchText value =
        client
            .sms()
            .batches()
            .send(
                SendSmsBatchTextRequest.builder()
                    .setTo(Collections.singletonList("YOUR_recipient_phone_number"))
                    .setBody("This is a test SMS message using the Sinch Java SDK.")
                    .setFrom("YOUR_sinch_phone_number")
                    .build());

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

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

package send.sms;

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"
      , "{"
      , " \"from\": \"YOUR_Sinch_virtual_number\","
      , " \"to\": ["
      , "  \"YOUR_recipient_number\""
      , " ],"
      , " \"body\": \"YOUR_message_body\","
      , " \"delivery_report\": \"summary\","
      , " \"type\": \"mt_text\""
      , "}"
    );

    var host = "https://";
    var servicePlanId = "YOUR_service_plan_id_PARAMETER";
    var region = "us";
    var pathname = region + ".sms.api.sinch.com/xms/v1/" + servicePlanId + "/batches";
    var request = HttpRequest.newBuilder()
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .uri(URI.create(host + pathname ))
      .header("Content-Type", "application/json")
      .header("Authorization", "Bearer <YOUR_TOKEN_HERE>")
      .build();

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

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

package send.sms;

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.domains.sms.models.BatchText;
import com.sinch.sdk.domains.sms.models.requests.SendSmsBatchTextRequest;
import com.sinch.sdk.models.Configuration;
import com.sinch.sdk.models.SMSRegion;

import java.io.IOException;
import java.util.Collections;
import java.util.logging.Logger;

public class App {
    private static final Logger LOGGER = Logger.getLogger(App.class.getName());

  public App() throws IOException {}

  public static void main(String[] args) {
    try {
      new App().run();
    } catch (Exception e) {
      LOGGER.severe(e.getMessage());
      e.printStackTrace();
    }
  }

  public void run() {

    SinchClient client = new SinchClient(Configuration.builder()
                                    .setKeyId("YOUR_access_key")
                                    .setKeySecret("YOUR_access_secret")
                                    .setProjectId("YOUR_project_id")
                                    .setSmsRegion(SMSRegion.US)
                                    .build());


    LOGGER.info("Send Text");
    BatchText value =
        client
            .sms()
            .batches()
            .send(
                SendSmsBatchTextRequest.builder()
                    .setTo(Collections.singletonList("YOUR_recipient_phone_number"))
                    .setBody("This is a test SMS message using the Sinch Java SDK.")
                    .setFrom("YOUR_sinch_phone_number")
                    .build());

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

Note that the REST API uses the Service Plan ID and and API token instead of Project ID and access keys.

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

• Client initialization
• 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 sms.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)
                                  .setSmsRegion(SMSRegion.US)
                                  .build());
}

Sms domain

Endpoint categories

In the Sinch Java SDK, SMS API endpoints are accessible through the client. The naming convention of the endpoints in the SDK resembles the API:

• groups()
• batches()
• inbounds()
• deliveryReports()

For example:

var batches = client.sms().batches().list(BatchesListRequestParameters.builder()
                                                .setPage(1)
                                                .setPageSize(10)
                                                .setFrom("YOUR_from_number")
                                                .setStartDate("2023-11-01T00:00:00.00")
                                                .setEndDate("2023-11-30T00:00:00.00")
                                                .setClientReference("YOUR_reference")
                                                .build());

The field mappings are described in the sections below.

sms().batches() endpoint category

sms().deliveryReports() endpoint category

sms().groups() endpoint category

sms().inbounds() endpoint category

Request and query parameters

Requests and queries made using the Java SDK are similar to those made using the SMS API. Many of the fields are named and structured similarly. For example, consider the representations of an SMS API message type. One field is represented in JSON, and the other is using our Java SDK:

DeliveryReportType.FULL

"delivery_report": "full"

Many fields in the Java SDK are rendered as enums in data models.

Nested objects

When making calls directly to the API, we use JSON objects, including (in some cases) nested JSON objects. When using the Java SDK, we use Java data models instead of nested JSON objects. For example, consider the SMS configuration objects below. One is represented in JSON, the other as a Java object:

SendSmsBatchTextRequest.builder()
                    .setTo(Collections.singletonList("YOUR_recipient_phone_number"))
                    .setBody("Test message using Java SDK")
                    .setFrom("YOUR_sinch_phone_number")
                    .setDeliveryReport(DeliveryReportType.NONE)
                    .build()

{
"from": "YOUR_Sinch_number",
"to": [
"YOUR_number"
],
"body": "Hello from Sinch!",
"delivery_report": "none",
"type": "mt_text"
}

Responses

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