Handle an incoming call with Java SDK

Now that you know how to call yourself using the Voice API, learn how to handle incoming calls.

In this guide you will learn:

1. How to set up your Node.js application
2. How to start your web server and set up a tunnel
3. About callbacks
4. How to call your server

Set up your Java application

1. Create a new folder where you want to store your application. Open a command prompt or terminal to that location and execute the following command:
   Copy

   Copied

   gradle init

   This command starts up the process to create a new blank Java application. You can select the default options for most of the prompts, but ensure you select that you want to create an application.

   Note:

   This guide assumes you're using Gradle but if you want to use another Java build tool, we've provided installation instructions for the most popular ones below.

2. Open App.java in your favorite editor and copy/paste in the App.java sample found on this page. Remember to keep your own package com.

Now that you've set up your application file, you must install the SDK itself and populate the code sample with your corresponding information.

The easiest way to install the SDK is using the Maven central repository.

Installing the SDK

You can create your Java project using your favorite method. Once your project is created, you need to add the SDK as a dependency. Depending on if you are using Gradle or Maven, you can add the necessary dependencies in the following ways:

Gradle

...
repositories {
    ...
    mavenCentral()
    ...
}
...

dependencies {
    ...
    implementation 'com.sinch.sdk:sinch-sdk-java:+'
    ...
}
...

...
repositories {
    ...
    mavenLocal()
    ...
}
...

dependencies {
    ...
    implementation("com.sinch.sdk:sinch-sdk-java:+")
    ...
}
...

Maven

<dependency>
    <groupId>com.sinch.sdk</groupId>
    <artifactId>sinch-sdk-java</artifactId>
    <version>LATEST</version>
</dependency>

Modify your application

The code provided in App.java includes placeholder parameters. You'll need to update the parameters detailed in the following subsections with your values.

Initialize the client

To start using the SDK, you need to initialize the main client class and create a configuration object to connect to your Sinch account and Voice app. You can find all of the credentials you need on your Sinch dashboard.

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.models.Configuration;

public class App {
    
    public static void main(String[] args) {
        SinchClient client = new SinchClient(Configuration.builder()
                                    .setApplicationKey("YOUR_application_key")
                                    .setApplicationSecret("YOUR_application_secret")
                                    .build());
    }
}

Save the file.

Start your web server and set up a tunnel

1. Start the server by executing the following command:
   Copy

   Copied

   gradle run

2. Open a tunnel to the server you just set up. We are using ngrok for this. If you don't have ngrok installed already, install it with the following command:
   Copy

   Copied

   npm install ngrok -g

3. Open a terminal or command prompt and enter:
   Copy

   Copied

   ngrok http <YOUR_PORT_NUMBER>

   In your console you will see an ngrok URL. Copy that URL and append /voice/webhook to the end of it so that it looks something like <ngrok-url>/voice/webhook.
4. Navigate to your app on your dashboard. Under the Settings section, you'll see a field labeled "Callback URL." Enter your URL into that field and click Save.

Now your server is listening and your callback URL is configured, so you're almost ready to test everything and make a phone call. But before we do, let's take a closer look at callbacks. If you already know about callbacks, skip right to calling your Sinch phone number.

Understanding callbacks

Callbacks (also known as "webhooks") are the method that the Voice API uses to figure out what you want to do with a call. Basically, a callback is a request that the Sinch servers send to your server whenever something happens (otherwise known as an "event") in the call that requires some input from you. There are a few different types of events, but the two we are concerned about for this guide are the Incoming Call Event and the Disconnected Call Event.

An Incoming Call Event happens whenever someone calls one of your Sinch numbers. In essence, someone dials your number and so Sinch servers reach out to you and say "how do you want me to handle this call?"

Most callback events expect a response, depending on the event. The Incoming Call Event expects to receive back a SVAML object in response. You can read more about SVAML here, but just know that SVAML is a markup language Sinch developed to control calls.

The below diagram demonstrates exactly what's happening:

1. Someone dials your Sinch number from a handset.
2. The Sinch servers create an ICE and send a POST request to your server.
3. Your server listens for the request and sends back a SVAML response to tell the Sinch server how to handle the call.

In this sample application, this is the SVAML object that you will use to respond to the callback (we've also provided the underlying JSON SVAML object for comparison):

var hangupAction = ActionHangUp.builder()
                            .build();
var sayInstruction = InstructionSay.builder()
                            .setText("Thank you for calling Sinch. This call will now end.")
                            .build();
            
SVAMLControl response = SVAMLControl.builder()
                            .setInstructions(Collections.singletonList(sayInstruction))
                            .setAction(hangupAction)
                            .build();

{
  "instructions": [
    {
      "name": "say",
      "text": "Thank you for calling Sinch! This call will now end..",
      "local": "en-US"
    }
  ],
  "action": {
    "name": "hangup"
  }
}

This SVAML object has two parts: instructions and an action. Instructions are things you want to be done on the call without changing the state of the call. In this case, we want to play a voice that reads out a text message. Actions are things you want to be done to the call to change its state in some way. In this case, we want to hang up and end the call.

voiceService.webhooks().serializeWebhooksResponse(response);

And that's it! Now we can test.

Call your Sinch phone number

Look up the free Sinch number assigned to your app and call it using your phone. The call should be picked up by the Sinch servers and you should hear the text from the instruction. Now you know how to handle an incoming call.

Next steps

Learn more about the Voice API:

• API specification