# Sinch Java SDK for SMS The Sinch Java SDK allows you to quickly interact with the from inside your Java applications. When using the Java SDK, the code representing requests and queries sent to and responses received from the are structured similarly to those that are sent and received using the . The fastest way to get started with the SDK is to check out our [getting started](/docs/sms/getting-started/java/send-sms-sdk) guides. There you'll find all the instructions necessary to download, install, set up, and start using the SDK. Note: You can also view the generated JavaDocs for the Java SDK [here](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/package-summary.html). ## Syntax Note: This guide describes the syntactical structure of the Java SDK for the SMS API, including any differences that may exist between the API itself and the SDK. For a full reference on SMS API calls and responses, see the [SMS API Reference](/docs/sms/api-reference/). The code sample below is an example of how to use the Java SDK to send an SMS message. We've also provided an example that accomplishes the same task using the REST API. SDK App.java //Use this code to send an SMS message. package sms; import com.sinch.sdk.domains.sms.api.v1.BatchesService; import com.sinch.sdk.domains.sms.api.v1.SMSService; import com.sinch.sdk.domains.sms.models.v1.batches.request.TextRequest; import com.sinch.sdk.domains.sms.models.v1.batches.response.BatchResponse; import java.util.Collections; import java.util.logging.Logger; public class Snippet { private static final Logger LOGGER = Logger.getLogger(Snippet.class.getName()); static void execute(SMSService smsService) { BatchesService batchesService = smsService.batches(); String from = "YOUR_sinch_phone_number"; String recipient = "YOUR_recipient_phone_number"; String body = "This is a test SMS message using the Sinch Java SDK."; LOGGER.info(String.format("Submitting batch to send SMS to '%s'", recipient)); BatchResponse value = batchesService.send( TextRequest.builder() .setTo(Collections.singletonList(recipient)) .setBody(body) .setFrom(from) .build()); LOGGER.info("Response: " + value); } } REST API ```java 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 ") .build(); var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` 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](#client) - [Endpoint usage](#endpoint-categories) - [Field population](#request-and-query-parameters) ## 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: ```java 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()); } ``` Note: The above sample specifies the US region. If you want to specify the European region, you can use `.setSmsRegion(SMSRegion.EU)`. ## Sms 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.sms.[endpoint_category()].[method()]`. 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: ```java 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. The `sms().batches()` category of the Java SDK corresponds to the [batches](/docs/sms/api-reference/sms/batches/) endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page: | API operation | SDK method | JavaDocs | | --- | --- | --- | | [Send](/docs/sms/api-reference/sms/batches/sendsms) | `send()` | [send](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#send(com.sinch.sdk.domains.sms.models.BaseBatch)) | | [List batches](docs/sms/api-reference/sms/batches/listbatches) | `list()` | [list](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#list(com.sinch.sdk.domains.sms.models.requests.BatchesListRequestParameters)) | | [Dry run](/docs/sms/api-reference/sms/batches/dry_run) | `dryRun()` | [dryRun](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#dryRun(boolean,int,com.sinch.sdk.domains.sms.models.BaseBatch)) | | [Get a batch message](/docs/sms/api-reference/sms/batches/getbatchmessage) | `get()` | [get](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#get(java.lang.String)) | | [Update a batch message](/docs/sms/api-reference/sms/batches/updatebatchmessage) | `update()` | [update](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#update(java.lang.String,com.sinch.sdk.domains.sms.models.requests.UpdateBaseBatchRequest)) | | [Replace a batch](/docs/sms/api-reference/sms/batches/replacebatch) | `replace()` | [replace](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#replace(java.lang.String,com.sinch.sdk.domains.sms.models.BaseBatch)) | | [Cancel a batch message](/docs/sms/api-reference/sms/batches/cancelbatchmessage) | `cancel()` | [cancel](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#cancel(java.lang.String)) | | [Send delivery feedback for a message](/docs/sms/api-reference/sms/batches/deliveryfeedback) | `sendDeliveryFeedback()` | [sendDeliveryFeedback](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/batchesService.html#sendDeliveryFeedback(java.lang.String,java.util.Collection)) | The `sms().deliveryReports()` category of the Java SDK corresponds to the [delivery_report and delivery_reports](/docs/sms/api-reference/sms/delivery-reports/) endpoints. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page: | API operation | SDK method | JavaDocs | | --- | --- | --- | | [Retrieve a delivery report](/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbybatchid) | `get()` | [get](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/DeliveryReportsService.html#get(java.lang.String,com.sinch.sdk.domains.sms.models.requests.DeliveryReportBatchGetRequestParameters)) | | [Retrieve a recipient delivery report](/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbyphonenumber) | `getForNumber()` | [getForNumber](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/DeliveryReportsService.html#getForNumber(java.lang.String,java.lang.String)) | | [Retrieve a list of delivery reports](/docs/sms/api-reference/sms/delivery-reports/getdeliveryreports) | `list()` | [list](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/DeliveryReportsService.html#list(com.sinch.sdk.domains.sms.models.requests.DeliveryReportListRequestParameters)) | The `sms().groups()` category of the Java SDK corresponds to the [groups](/docs/sms/api-reference/sms/groups/) endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page: | API operation | SDK method | JavaDocs | | --- | --- | --- | | [List groups](/docs/sms/api-reference/sms/groups/listgroups) | `list()` | [list](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#list()) | | [Create a group](/docs/sms/api-reference/sms/groups/creategroup) | `create()` | [create](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#create(com.sinch.sdk.domains.sms.models.requests.GroupCreateRequestParameters)) | | [Retrieve a group](/docs/sms/api-reference/sms/groups/retrievegroup) | `get()` | [get](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#get(java.lang.String)) | | [Update a group](/docs/sms/api-reference/sms/groups/updategroup) | `update()` | [update](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#update(java.lang.String,com.sinch.sdk.domains.sms.models.requests.GroupUpdateRequestParameters)) | | [Replace a group](/docs/sms/api-reference/sms/groups/replacegroup) | `replace()` | [replace](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#replace(java.lang.String,com.sinch.sdk.domains.sms.models.requests.GroupReplaceRequestParameters)) | | [Delete a group](/docs/sms/api-reference/sms/groups/deletegroup) | `delete()` | [delete](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#delete(java.lang.String)) | | [List group member phone numbers](/docs/sms/api-reference/sms/groups/getmembers) | `listMembers()` | [listMembers](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/GroupsService.html#listMembers(java.lang.String)) | The `sms().inbounds()` category of the Java SDK corresponds to the [inbounds](/docs/sms/api-reference/sms/inbounds/) endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page: | API operation | SDK method | JavaDocs | | --- | --- | --- | | [List incoming messages](/docs/sms/api-reference/sms/inbounds/listinboundmessages) | `list()` | [list](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/InboundsService.html#get(java.lang.String)) | | [Retrieve inbound message](/docs/sms/api-reference/sms/inbounds/retrieveinboundmessage) | `get()` | [get](https://www.javadoc.io/doc/com.sinch.sdk/sinch-sdk-java/latest/com/sinch/sdk/domains/sms/InboundsService.html#get(java.lang.String)) | 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: SDK ```java DeliveryReportType.FULL ``` REST API ```JSON "delivery_report": "full" ``` Many fields in the Java SDK are rendered as enums in data models. 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: SDK ```Java SendSmsBatchTextRequest.builder() .setTo(Collections.singletonList("YOUR_recipient_phone_number")) .setBody("Test message using Java SDK") .setFrom("YOUR_sinch_phone_number") .setDeliveryReport(DeliveryReportType.NONE) .build() ``` REST API ```JSON { "from": "YOUR_Sinch_number", "to": [ "YOUR_number" ], "body": "Hello from Sinch!", "delivery_report": "none", "type": "mt_text" } ``` Note that in the Java SDK you would use a `builder()` method to construct the appropriate data model in the correct structure. Note also that while in the raw JSON request body you can specify the message type, the Java SDK has a specific Batch request object for each message type. Response fields match the API responses. They are delivered as Java objects.