# Receive an SMS Message with Java

 Note:
Before you can get started, you need the following already set up:

- 
- [JDK 11 or later](https://www.oracle.com/java/technologies/downloads/) and a familiarity with how to create a new Java application.
- [Gradle](https://gradle.org/install/) and a familiarity with how use the Gradle build tools.
- [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server.


Handle and reply to incoming SMS Messages to your Sinch number.

When someone sends an SMS message to your Sinch number, we will send an `http` request to your server. This is known as a callback or webhook. You can configure your webhooks in your [SMS API settings](https://dashboard.sinch.com/sms/api).

Learn how to quickly set up a Java server to receive SMS messages with the Sinch API using the Spark web application framework.

Steps:
1. [Install](#install-the-sinch-sdk-for-java) the Sinch Java library
2. [Configure](#configure-your-callback-url) your callback URL
3. [Send](#send-your-sms-message) your SMS message


## Install the Sinch SDK for Java

1. If you don't have a java project already, create one:

```shell
gradle init
```
2. Select your application, and then accept all default values.


### Add Gradle dependencies

To listen to incoming HTTP requests, we will use Spark.

In your `build.gradle` file add the following three dependencies:


```javascript
dependencies {
  implementation 'com.sinch:sdk-sms:1.0.+'
  implementation group: "com.sparkjava", name: "spark-core", version: "2.9.3"
  implementation group: 'org.slf4j', name: 'slf4j-simple', version: '1.7.31'
}
```

### Update the App.java file

When you have installed the SDK and have a Java project you are ready to write some code.

Change your `App.java` to the supplied code.

Receive an SMS message

```java Receive an SMS message
// Find your servicePlanId and Token at https://dashboard.sinch.com/sms/api/rest
// Install the Java helper library at https://developers.sinch.com/docs/sms/sdks/java-legacy/
// Find your Sinch virtual number at // https://dashboard.sinch.com/numbers/your-numbers

import com.sinch.xms.*;
import com.sinch.xms.api.*;

import static spark.Spark.*;

public class App {
	private static final String SERVICE_PLAN_ID = "YOUR_servicePlanId";
	private static final String TOKEN = "YOUR_API_token";
	private static ApiConnection conn;
    private static ApiObjectMapper mapper = new ApiObjectMapper();

	public static void main(String[] args) {
       
        conn = ApiConnection
                .builder()
                .servicePlanId(SERVICE_PLAN_ID)
                .token(TOKEN)
                .start();
        get("/", (req, res) -> "The server is up and running");
      
        post("/", (request, response) -> {
            MoTextSms message = mapper.readValue(request.body(), MoTextSms.class);
            String[] RECIPIENTS = { message.sender() };
            String SENDER = message.recipient();
            MtBatchTextSmsCreate reply = SinchSMSApi
                                            .batchTextSms()
                                            .sender(SENDER)
                                            .addRecipient(RECIPIENTS)
                    						.body("You sent: " + message.body())
											.build();
                try {
                // if there is something wrong with the batch
                // it will be exposed in APIError
                MtBatchTextSmsResult batch = conn.createBatch(reply);
                System.out.println(batch.id());
            } catch (Exception e) {
                System.out.println(e.getMessage());
            }
            System.out.println("incoming message:" + message);
            return "incoming message:" + message;
        });
	}
}
```

### Fill in your parameters

Change the following parameters in the code to your values:

| Parameter | Your value |
|  --- | --- |
| `SERVICE_PLAN_ID` | The service plan ID found on your [Sinch Build Dashboard](https://dashboard.sinch.com/sms/api/rest). |
| `TOKEN` | The API token found on your [Sinch Build Dashboard](https://dashboard.sinch.com/sms/api/rest). Click Show to reveal your API token. |


Double check that the region is correct on your base URL. Learn more about [regional options here](/docs/sms/api-reference#base-url).

### Set up an ngrok tunnel and run your application

1. In the terminal or command prompt window, start running your application with:

```shell
gradle run
```
2. Before you can handle incoming traffic to your local server, open up a tunnel to your local server. For that, you can use an [ngrok](https://ngrok.com/) tunnel.
If you haven't already, install ngrok, and then open a terminal or command prompt. Take note of the URL that ends in `.ngrok.io`.



```shell
ngrok http 4567
```

## Configure your Callback URL

You need to configure a Callback URL for your Sinch account. Login to your [Sinch Build Dashboard](https://dashboard.sinch.com/sms/api/rest). Click on the service plan ID link and edit the Callback URL field with the ngrok.io domain URL from the previous section.

## Send your SMS message

Now send an SMS message to your Sinch number from your mobile phone and you will get an automatic reply.

## Next Steps

- Explore the [API specification](/docs/sms/api-reference/) to test more endpoints.