Docs
BetaSDKsGet startedTalk to salesSign inSupportStatusPricing

Voice Verify API - Tutorial: Send a voice message with verification code with Telesign Java SDK

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This tutorial teaches you how to use Telesign Voice Verify API with a Java SDK, by walking you step-by-step through the creation of an integration where you send your own verification code to an end-user. Skip to the end of this page to see the full, completed sample code.

Before you begin

Make sure you have the following before you start:

  • Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
  • Testing device: A mobile phone on which you can receive a call.
  • Gradle: This package manager isn't required to use the SDK, but it is required for this tutorial.

📘

NOTE:

This tutorial uses the following:

  • MacOS
  • Java OpenJDK v19.0.1
  • Gradle 7.6

Please modify accordingly if your developer environment differs from these details.

Set up your project

  1. Follow the Telesign Full-service Java SDK install instructions here on GitHub incorporating these details:

    • Use voice_verify as the project directory name.
    • Use JUnit 4 as the test framework.
    • Use sendVoice as the project name.
    • Use sendVoice as the source package name.

    You should end up in the top-level directory ("voice_verify") for your project in the Terminal. This directory should contain an initialized Gradle project with the Telesign Full-service SDK included in its dependencies.

  2. From the top level of your project, delete the folder "app/src/test/". No tests are included in this tutorial.

rm -r app/src/test/
  1. Open the file "build.gradle.kts". At the bottom of this file, add the following declaration. This is needed to enable the Scanner utility to work properly with Gradle. We'll be using Scanner to collect input on the command line.
tasks.named<JavaExec>("run") {
    standardInput = System.`in`
}

Send a voice message with a verification code

  1. Open the file "app/src/main/java/sendVoice/App.java".

  2. Follow the steps below or copy the sample code into the file and update it accordingly.

  3. Add the imports below between the package declaration. These imports reference selected functionality from the Telesign Full-service SDKs, as well as some other Java utilities.

package voice_verify; // The source package name you specified when creating the project

import com.telesign.RestClient;
import com.telesign.Util;
import com.telesign.enterprise.VerifyClient;

import java.util.HashMap;
import java.util.Scanner;
  1. Add the App class declaration and with the following basic structure.
public class App {
    public static void main(String[] args) {
    
    }
}

In the next step, you will begin adding statements to the main function in the App class.

  1. Define variables in the main function to store your authentication credentials. For testing purposes, you can just overwrite the default values below or use environment variables.
String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
String apiKey = System.getenv().getOrDefault("API_KEY", "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");
  1. Define a variable in the main function to hold the phone number you want to a send voice message to. This should be a string with no spaces or special characters. Use the complete number, including the country code. For example: 16505551212.
String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "123456789");

📘

NOTE:

In your production integration, pull the phone number from your recipient database instead of hardcoding it.

  1. Generate a verification code.
String verifyCode = Util.randomWithNDigits(5);
HashMap<String, String> params = new HashMap<>();
params.put("verify_code", verifyCode);
  1. Create a try-catch structure.
try {

} catch (Exception e) {

}
  1. In the try block, create a VerifyClient object and pass it your customerId and apiKey.
VerifyClient verifyClient = new VerifyClient(customerId, apiKey);
  1. Next in the try block, send a voice message containing the verification code you created. Store the results of your request in the telesignResponse variable. 
RestClient.TelesignResponse telesignResponse = verifyClient.voice(phoneNumber, params);
  1. Next in the try block, have the end user input the verification code they received.
Scanner s = new Scanner(System.in);
System.out.println("Please enter your verification code:");
String code = s.next();
  1. Check it to see if the verification code is valid and print the results of the check.
if (verifyCode.equalsIgnoreCase(code)) {
    System.out.println("Your code is correct.");
} else {
    System.out.println("Your code is incorrect.");
}
  1. In the catch block, add code to display any type of exception and associated error code that might occur. Again, this is for debugging purposes. In your production code, you would likely remove this.
 e.printStackTrace();

Test your integration

  1. Switch from your editor to the terminal and build the project:
./gradlew build
  1. Run the project:
./gradlew run

If all goes well, you should send a voice message containing a verification code to the phone number you selected. If you are testing with your phone, you should be able to enter the verification code in response to a prompt from your terminal. The sample will then check your verification code to see if it matches the verification code that was sent and report on the results.

Send a Voice Message with Verification Code in a Different Language

This section explains how to send a custom voice message in a different language using Voice Verify API. A sample is provided here if you want to cut and paste. Note that the only difference between this code sample and the previous code sample in this tutorial is that you use the tts_message (text-to-speech) parameter to enter a custom message, and the language parameter to specify the language. For a list of language codes, refer to - Voice Verify API - Supported languages for text-to-speech.

package voice_verify; // The source package name you specified when creating the project

import com.telesign.RestClient;
import com.telesign.enterprise.VerifyClient;

import java.util.HashMap;
import java.util.Scanner;

public class App {

    public static void main(String[] args) {

        String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
        String apiKey = System.getenv().getOrDefault("API_KEY", "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");

        String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "123456789"); //Your test phone number with no special characters or spaces goes here.
        String language = "fr-FR";
      	String verifyCode = Util.randomWithNDigits(5);
        String ttsMessage = "Votre code de vérification Widgets 'n' More est " + verifyCode;

        HashMap<String, String> params = new HashMap<>();
        params.put("language", language);
        params.put("tts_message", ttsMessage);

        try {
            VerifyClient verifyClient = new VerifyClient(customerId, apiKey);
            RestClient.TelesignResponse telesignResponse = verifyClient.voice(phoneNumber, params);
          
            Scanner s = new Scanner(System.in);
            System.out.println(telesignResponse.body);
            System.out.println("Please enter your verification code:");
            String code = s.next();

            if (verifyCode.equalsIgnoreCase(code)) {
                System.out.println("Your code is correct.");
            } else {
                System.out.println("Your code is incorrect.");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Sample code

package voice_verify; // The source package name you specified when creating the project

import com.telesign.RestClient;
import com.telesign.Util;
import com.telesign.enterprise.VerifyClient;

import java.util.HashMap;
import java.util.Scanner;

public class App {

    public static void main(String[] args) {

        String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
        String apiKey = System.getenv().getOrDefault("API_KEY", "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");

        String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "123456789"); //Your test phone number with no special characters or spaces goes here.
        String verifyCode = Util.randomWithNDigits(5);

        HashMap<String, String> params = new HashMap<>();
        params.put("verify_code", verifyCode);

        try {
            VerifyClient verifyClient = new VerifyClient(customerId, apiKey);
            RestClient.TelesignResponse telesignResponse = verifyClient.voice(phoneNumber, params);

            Scanner s = new Scanner(System.in);
            System.out.println("Please enter your verification code:");
            String code = s.next();

            if (verifyCode.equalsIgnoreCase(code)) {
                System.out.println("Your code is correct.");
            } else {
                System.out.println("Your code is incorrect.");
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Updated about 6 hours ago

© 2025 Telesign / Terms & Conditions / Privacy Notice / Privacy Hub