# Legacy SDK to Unified SDK Migration Guide

As of April 15, 2025, the Legacy Sinch SDK ([com.sinch.sdk-sms](https://mvnrepository.com/artifact/com.sinch/sdk-sms)) is no longer supported. If you are an exisiting Sinch customer using the Legacy Sinch SDK, we encourage you to migrate to the Unified Sinch SDK ([com.sinch.sdk.sinch-sdk-java](https://mvnrepository.com/artifact/com.sinch.sdk/sinch-sdk-java)).

Note:
While the Legacy Sinch SDK for Java is planned for deprecation, there is currently **no hard deadline** for migration. The artifact will remain available for continued use. However, please note that **no further updates** (including API changes or bug fixes) will be provided for the Legacy Sinch SDK for Java. We recommend migrating to the new SDK to benefit from ongoing improvements and support.

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](#client-initialization)
- [Construction of the message](#message-construction)


## 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:


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

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


```java
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](/docs/sms/sdks/java/syntax-reference/#client).

## 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.


```java
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);
```


```java
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:

| Legacy Sinch SDK | Unified Sinch SDK |
|  --- | --- |
| `.sender()` | `.setFrom()` |
| `.addRecipient()` | `.setTo()` |
| `.body()` | `.setBody()` |
| `.createBatch()` | `.send()` |


For more information on the Unified Java SDK and the corresponding syntax, see the [Java SDK syntax reference guide for SMS](/docs/sms/sdks/java/syntax-reference). This syntax guide includes more detail on each SMS method available in the SDK, links to related [JavaDocs](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/index.html), and can be combined with the [SMS REST API reference guide](/docs/sms/api-reference/) 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:


```java
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);
```


```java
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:

| Legacy Sinch SDK | Unified Sinch SDK |
|  --- | --- |
| `.sender()` | `.setFrom()` |
| `.addRecipient()` | `.setTo()` |
| `.body()` | `.setBody()` |
| `.url()` | `.setUrl()` |
| `.message()` | `.setMessage()` |
| `.createBatch()` | `.send()` |


#### 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:


```java
// 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());
```


```java
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:

| Legacy Sinch SDK | Unified Sinch SDK |
|  --- | --- |
| `.name()` | `.setName()` |
| `.addMemberInsertion()` | `.setAdd()` |
| `group.id()` | `group.getId()` |
| `.addRecipient()` | `.setTo()` |
| `.body()` | `.setBody()` |
| `.createBatch()` | `.send()` |