Make a call with Java

You can quickly see how the Voice API works by calling yourself using the API.

In this guide you will learn:

How to set up your Java application.
How to call your phone number.

What you need to know before you start

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

Set all Voice API configuration settings.
JDK 8 or later and a familiarity with how to create a new Java application.
Gradle and a familiarity with how use the Gradle build tools.

Set up your Java application

Create a new folder where you want to keep your app project. Then, open a terminal or command prompt to that location.

Create a new Java application using Gradle with the following command:

Copy

Copied

gradle init

In the prompts, select that you want to create an application, name your project and source package app, and then accept the defaults for the rest of the options.

Modify your application

Open the App.java file in your project folder, located in \app\scr\main\java\app, and populate that file with the "App.java" code found on this page.

Note:

This tutorial uses basic authentication for testing purposes. We recommend using a signed request for authentication in a production environment. You can follow the steps in this guide, but use the code samples from here to use request signing authentication instead.

App.java

Use this code to make a phone call using the Voice API.

package app;

import java.net.*;
import java.net.http.*;
import java.util.*;

public class App {
  private static final String key = "";
  private static final String secret = "";
  private static final String fromNumber = "";
  private static final String to = "";
  private static final String locale = "";

  public static void main(String[] args) throws Exception {
    var httpClient = HttpClient.newBuilder().build();

    var payload = String.join("\n"
      , "{"
      , " \"method\": \"ttsCallout\","
      , " \"ttsCallout\": {"
      , "  \"cli\": \"" + fromNumber + "\","
      , "  \"destination\": {"
      , "   \"type\": \"number\","
      , "   \"endpoint\": \"" + to + "\""
      , "  },"
      , "  \"locale\": \"" + locale + "\","
      , "  \"text\": \"Hello, this is a call from Sinch. Congratulations! You made your first call.\""
      , " }"
      , "}"
    );

    var host = "https://calling.api.sinch.com";
    var pathname = "/calling/v1/callouts";
    var request = HttpRequest.newBuilder()
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .uri(URI.create(host + pathname ))
      .header("Content-Type", "application/json")
      .header("Authorization", "Basic " + Base64.getEncoder().encodeToString((key + ":" + secret).getBytes()))
      .build();

    var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

This code makes a POST request to the Voice API /callouts endpoint which then makes a call out to the to parameter in the body of the request. The Voice API uses callouts to make voice calls. In this guide, we are using the ttsCallout or "text-to-speech callout" to call a number and then play a text-to-speech message before hanging up.

To

In this example you want to call a phone number. Change the value of the to parameter to the phone number you verified in your dashboard in E.164 format.

Note:

When your account is in trial mode, you can only call your verified numbers. If you want to call any number, you need to upgrade your account!

Fill in your parameters

Before you can run the code, you need to update some more values so you can connect to your Sinch account. Update the following parameters with your own values:

Parameter	Your value
`key`	The application key found on your Sinch dashboard. Click on your application to find the key.
`secret`	The application secret found on your Sinch dashboard. Click on your application to fine the secret.
`fromNumber`	Any number you've assigned to your application. This can be a number you've purchased or your free test number. Find the number on your Sinch dashboard by clicking on your app and looking in the Inbound Numbers section.
`locale`	The language and locale you want to use for the text-to-speech call. Locale is specified with a language code according to `ISO 639`, a dash and a country code according to `ISO 3166-1 alpha-2`. For example, American English is represented by `en-US`.

Save the file.

Make your first call

Now you can execute the code and make your text-to-speech call. Run the following command:

Copy

Copied

gradle run

You should receive a phone call to the number you called with the message "Hello, this is a call from Sinch. Congratulations! You made your first call."

Tip:

If the text-to-speech message starts playing too early for your needs, you can use SSML to add a pause at the beginning of the message.

Troubleshooting tip

If after running your app you receive a 5000 error response, you may have forgotten to save your file after adding your authentication values. This is an easy mistake to make! Try saving the file and running the app again.

Next steps

Now that you know how to make a call, learn how to handle an incoming call.

Additional resources

API specification