Legacy SDK to Unified SDK Migration Guide

The Legacy Sinch SDK (com.sinch.sdk-sms) for Java will be deprecated in the near future. If you are an exisiting Sinch customer using the Legacy Sinch SDK, you must migrate to the Unified Sinch SDK (com.sinch.sdk.sinch-sdk-java). This guide provides guidelines on how to migrate to the Unified Sinch SDK from the Legacy Sinch SDK. Specifically, this guide provides general reference material and examples to aid you in your migration.

When migrating away from the Legacy Sinch SDK, you must update your code to use the Unified Sinch SDK. This guide provides examples for the following transformations:

• Client initialization
• Construction of the message

Client initialization

For both SDKs, you must initalize a client in order to access the rest of the SDK's functionality.

• The client is referred to as an APIConnection in the Legacy Sinch SDK.
• The client is referred to as an SinchClient in the Unified Sinch SDK.

Whereas the Legacy Sinch SDK only made use of the servicePlanId during initialization, the Unified Sinch SDK supports the use of both service_plan_id and project_id for account identification and authentication.

Below are examples of initaiting each type of client:

String servicePlanId = "SERVICE_PLAN_ID";
String token = "SERVICE_TOKEN";

ApiConnection conn = ApiConnection.builder()
    .servicePlanId(servicePlanId)
    .token(token)
    .start();

String servicePlanId = "SERVICE_PLAN_ID";
String token = "SERVICE_TOKEN";

Configuration configuration = Configuration.builder()
    .setSmsServicePlanId(servicePlanId)
    .setSmsApiToken(token)
    .build();

SinchClient client = new SinchClient(configuration);

Additional information about client initialization can be found in the Java SDK syntax reference guide for SMS.

Message Construction

There are only minor syntactical differences between the construction of a message using the legacy SDK and the construction of a message using the Unified Sinch SDK.

String sender = "SENDER"; // Optional, must be valid phone number, short code or alphanumeric.
String[] recipients = {"1232323131", "3213123"};
String body= "Something good";

MtBatchTextSmsCreate request = SinchSMSApi.batchTextSms()
    .sender(sender)
    .addRecipient(recipients)
    .body(body)
    .build();

MtBatchTextSmsResult batch = conn.createBatch(request);

BatchesService service = client.sms().v1().batches();

String sender = "SENDER"; // Optional, must be valid phone number, short code or alphanumeric.
List<String> recipients = Arrays.asList("1232323131", "3213123");
String body= "Something good";

BatchRequest request = TextRequest.builder()
    .setFrom(sender)
    .setTo(recipients)
    .setBody(body)
    .build();

BatchResponse batch = service.send(request);

Note that you must provide the same values when sending a message using either SDK. The options simply have slightly different naming conventions, which are mapped below:

For more information on the Unified Java SDK and the corresponding syntax, see the Java SDK syntax reference guide for SMS. This syntax guide includes more detail on each SMS method available in the SDK, links to related JavaDocs, and can be combined with the SMS REST API reference guide for a full explanation of the Unified Sinch SDK's SMS capabilities.

Additional Examples

The following sections include additional examples of common SMS SDK functionalities.

Sending an MMS message

Below are examples of how to send an MMS message using the Legacy Sinch SDK and the Unified Sinch SDK:

String sender = "SENDER"; // Optional, must be valid phone number, short code or alphanumeric.
String[] recipients = {"1232323131", "3213123"};

MediaBody body = SinchSMSApi.mediaBody()
    .url("https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png")
    .message("Hello, world!")
    .build();

MtBatchMmsCreate request = SinchSMSApi.batchMms()
    .sender(sender)
    .addRecipient(recipients)
    .body(body)
    .build();

conn.createBatch(request);

BatchesService service = client.sms().v1().batches();

String sender = "SENDER"; // Optional, must be valid phone number, short code or alphanumeric.
List<String> recipients = Arrays.asList("1232323131", "3213123");

MediaBody body = MediaBody.builder()
    .setUrl("https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png")
    .setMessage("Hello, world!")
    .build;

BatchRequest request = MediaRequest.builder()
    .setFrom(sender)
    .setTo(recipients)
    .setBody(body)
    .build();

service.send(request); 

The corresponding options are mapped below:

Creating groups and sending messages

Below are examples of how to create and update a group and, then, send a message to that group using the Legacy Sinch SDK and the Unified Sinch SDK:

// Creating simple Group
GroupCreate groupCreateRequest = SinchSMSApi.groupCreate()
      .name("Subscriber")
      .build();
GroupResult group = conn.createGroup(groupCreateRequest);

// Adding members (numbers) into the group
GroupUpdate groupUpdateRequest = SinchSMSApi.groupUpdate()
    .addMemberInsertion("15418888", "323232")
    .build();
conn.updateGroup(group.id(), groupUpdateRequest);

// Sending a message to the group
MtBatchTextSmsCreate smsRequest = SinchSMSApi.batchTextSms()
    .addRecipient(group.id().toString())
    .body("Something good")
    .build();

MtBatchTextSmsResult batch = conn.createBatch(smsRequest);

System.out.println("Successfully sent batch " + batch.id());

GroupsService groupService = client.sms().v1().groups();
BatchesService smsService = client.sms().v1().batches();

// Creating simple Group
GroupRequest groupCreateRequest = GroupRequest.builder()
    .setName("Subscriber")
    .build()
Group group = groupService.create();

// Adding members (numbers) into the group
GroupUpdateRequest groupUpdateRequest = GroupUpdateRequest.builder()
    .setAdd(Arrays.asList("15418888", "323232"))
    .build()
groupService.update(group.getId(), groupUpdateRequest);

// Sending a message to the group
List<String> recipients = Arrays.asList(group.getId());
String body= "Something good";

BatchRequest request = TextRequest.builder()
    .setTo(recipients)
    .setBody(body)
    .build();

BatchResponse batch = smsService.send(request);

System.out.println("Successfully sent batch " + batch.id());

The corresponding options are mapped below: