Sinch Developer Documentation

Building blocks to enable rich customer communication

Implementing SMS messaging in Java

Learn how to quickly send and receive SMS messages in Java applications with the Sinch API


This guide will walk you through the process of setting up a Java application to send and receieve SMS messages using the Sinch API.


Sign up for a Sinch account

Before you can send your first SMS, you need a Sinch
. If you are in the United States, you also need a free test phone number.

Image of configure numberImage of configure number
Click activate.

Image of configure numberImage of configure number
To use the number with the rest API select REST and click GET FREE TEST NUMBER.

Implementing SMS Messaging

A complete sample Java application can be found on GitHub at Send and Recieve SMS with Java and Spring Boot.

Sending SMS Messages

Executing the following code in your application will send an SMS message:

 private static final String[] RECIPIENTS = {"To number"};
 try (ApiConnection conn =
        ApiConnection.builder().servicePlanId(SERVICE_PLAN_ID).token(TOKEN).start()) {
      // Sending a simple Text Message
      MtBatchTextSmsResult batch =
                  .sender("{your free test number}")
                  .body("This is a test message!")

      System.out.println("Successfully sent batch " +;
    } catch (Exception e) {
      System.out.println("Batch send failed: " + e.getMessage());

Replacing the token values

Before you can execute the code that sends an SMS message, you need to replace the following values with your values:

  • {TOKEN}
  • {your free test number}
  • {To number}

To find the service plan ID and token, go to Dashboard, log in and click “Show” to reveal your API token.

Screen shot of dashboardScreen shot of dashboard

To find your free test number, click the service plan ID link and scroll to the bottom of the page. Then, change the {To number} to the phone number which will receive the SMS.

For more information about the batches endpoint, click here.

Handle incoming SMS with Java Spring Boot

When a customer sends an SMS to your number you can configure your application to receive a post to a webhook. You can use any framework you want that can expose an API endpoint.

For this guide we will use Spring Boot. If you are new to Spring Boot and want to try it out here is a good Quickstart.

If you are using the Quickstart repo, below is the Spring controller, located in

public class InboundController {
    public ResponseEntity<Object> receiveInbound(@RequestBody Object body) {
        return new ResponseEntity<>("Accepted", HttpStatus.OK);

Before you can handle incoming traffic to your local server, you need to open up a tunnel to your local server. For that, you can use an ngrok tunnel. If you haven't already, install ngrok, and then open a terminal/command prompt and type: ngrok http 3000.

ngrok requestngrok request

Configure the Callback URL for your SMS service

Before you implement the server to handle incoming SMS, you need to configure your SMS service to handle callbacks.

  1. Head over to Dashboard, click your service and you will see a section like the image below.

Screen shot of dashboardScreen shot of dashboard

  1. Under Callback URL, click Edit and configure a callback URL.

  2. In the terminal windows, start running the SpringBoot Application with ./gradlew bootRun if you are using Gradle or ./mvnw spring-boot:run if you are using Maven.

  3. Send an SMS to your Sinch number.

  4. You will now see the request come in.

requestbin requestrequestbin request

Read more about all the different endpoints in the API reference guide.

Edit on GitHub

Updated 28 days ago

Implementing SMS messaging in Java

Learn how to quickly send and receive SMS messages in Java applications with the Sinch API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.