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

📘
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 an 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.

Install the SDK

Sign in to GitHub and choose the SDK in your preferred language.
Download or clone the repository. If you download it, extract the repository from the .ZIP file.
Use these commands to install the SDK:

npm install telesignsdk -save

compile files('path/to/jar/telesignenterprise-(insert latest version).jar')

<dependency>
    <groupId>com.telesign</groupId>
    <artifactId>telesign</artifactId>
    <version>(insert latest version)</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/path/to/jar/telesignenterprise-(insert latest version).jar</systemPath>
</dependency>

# From a terminal run:
pip install -e ~/path/to/python_telesign_enterprise

#From a terminal run:
gem install telesign

# From a terminal run:
composer require telesign/telesign

# Build and install the TeleSignEnterprise package:
$ nuget pack .\Path\To\csharp_telesign_enterprise\TelesignEnterprise\TelesignEnterprise.csproj
$ Install-Package .\Path\To\TelesignEnterprise-(insert latest version).nupkg

Send a voice message with a verification code

This section explains how to send a voice message containing a verification code using Voice Verify API. The sample code provided earlier is broken out into pieces and explained below.

Begin by adding statements for including the appropriate part of the Telesign SDK and any additional language specific functions you may need.

var TeleSignSDK = require('telesignenterprisesdk');

package com.telesign.enterprise.example.verify_voice;

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

import java.util.HashMap;

from __future__ import print_function
from telesignenterprise.verify import VerifyClient
from telesign.util import random_with_n_digits

require 'telesign'
require 'telesignenterprise'

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\enterprise\sdk\verify\VerifyClient;
use function telesign\sdk\util\randomWithNDigits;

using System;
using System.Collections.Generic;
using Telesign;

Insert values for each of the items from customer_id/customerId through to phone_number/phoneNumber.

customer_id / customerId - Your Telesign-assigned Customer ID.
api_key / apiKey - Your Telesign-assigned API key.
phone_number / phoneNumber - The phone number to which you want to send the SMS. If you are doing a free trial, the phone number must be verified (verifying the number is not required if you are a paying customer). Include the complete phone number (with country code) including no spaces or special characters.

console.log("## verify.voice ##");

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
const phoneNumber = "Your test phone number with no special characters or spaces goes here.";

public class SendVoiceCallWithVerificationCode {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Your test phone number with no special characters or spaces goes here.";

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no special characters or spaces goes here."

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Your test phone number with no special characters or spaces goes here.'

$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces goes here.";

namespace TelesignEnterprise.Example.VerifyVoice
{
    class SendVoiceCallWithVerificationCode
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "Your test phone number with no special characters or spaces goes here.";

Generate a verification code.

const optionalParams = {verify_code: "32658"};

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

verify_code = random_with_n_digits(5)

verify_code = Telesign::Util.random_with_n_digits(5)

$verify_code = randomWithNDigits(5);

            string verifyCode = "12345";

            Dictionary<string, string> parameters = new Dictionary<string, string>();
            parameters.Add("verify_code", verifyCode);

Create a VerifyClient object and pass it your customer_id/customerId and api_key/apiKey.

const client = new TeleSignSDK(customerId, apiKey);

        try {
                VerifyClient verifyClient = new VerifyClient(customerId, apiKey);

verify = VerifyClient(customer_id, secret_key)

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, secret_key)

$verify = new VerifyClient($customer_id, $secret_key);

            try
            {
                VerifyClient verifyClient = new VerifyClient(customerId, apiKey);

Send a voice message containing the verification code you created. Store the results of your request in the response/telesignResponse variable. For Node.js, use this step to create a callback handler for the voice message you will eventually send and a method called inside voiceCallback that will handle user input.

// Callback handler for voice
function voiceCallback(error, responseBody) {
    if (error === null) {
        console.log(`Messaging response for messaging phone number: ${phoneNumber}` +
            ` => code: ${responseBody['status']['code']}` +
            `, description: ${responseBody['status']['description']}`);
      
        // Ask for user input
        prompt('Enter the verification code received:\n', function (input) {
            if (input === optionalParams['verify_code']) {
                console.log('Your code is correct.');
            } else {
                console.log('Your code is incorrect. input: ' + input + ", code: " + optionalParams['verify_code']);
            }
            process.exit();
        });

    } else {
        console.error("Unable to send voice call. " + error);
    }
}

// Method to handle user input
function prompt(question, callback) {
    const stdin = process.stdin,
        stdout = process.stdout;

    stdin.resume();
    stdout.write(question);

    stdin.once('data', function (data) {
        callback(data.toString().trim());
    });
}

            RestClient.TelesignResponse telesignResponse = verifyClient.voice(phoneNumber, params);

response = verify.voice(phone_number, verify_code=verify_code)

response = verify_client.voice(phone_number, verify_code: verify_code)

$response = $verify->voice($phone_number, [ "verify_code" => $verify_code ]);

               RestClient.TelesignResponse telesignResponse = verifyClient.Voice(phoneNumber, parameters);

Have the end user input the verification code they received, then check it to see if it is valid. Print the results of the check. For Node.js, you send the voice message here, and the callback and user input handler methods you defined in the last step are passed in through the voiceCallback method.

// Send Voice request
client.verify.voice(voiceCallback, phoneNumber, optionalParams);

            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();
        }
    }
}

user_entered_verify_code = raw_input("Please enter the verification code you were sent: ")

if verify_code == user_entered_verify_code.strip():
    print("Your code is correct.")
else:
    print("Your code is incorrect.")

print 'Please enter the verification code you were sent: '
user_entered_verify_code = gets.strip

if verify_code == user_entered_verify_code
  puts 'Your code is correct.'
else
  puts 'Your code is incorrect.'
end

echo "Please enter the verification code you were sent: ";
$user_entered_verify_code = trim(fgets(STDIN));
if ($verify_code == $user_entered_verify_code) {
  echo "Your code is correct.";
}
else {
  echo "Your code is incorrect.";
}

                Console.WriteLine("Please enter your verification code:");
                string code = Console.ReadLine().Trim();

                if (verifyCode == code)
                {
                    Console.WriteLine("Your code is correct.");
                }
                else
                {
                    Console.WriteLine("Your code is incorrect.");
                }

            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

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.

var TeleSignSDK = require('telesignenterprisesdk');

console.log("## verify.voice ##");

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
const phoneNumber = "Your test phone number with no special characters or spaces goes here.";
const optionalParams = {
    tts_message: "Votre code de vérification Widgets 'n' More est $$CODE$$.",
    language: "fr-FR"
};

const client = new TeleSignSDK(customerId, apiKey);

// Callback handler for voice
function voiceCallback(error, responseBody) {
    if (error === null) {
        console.log(`SMS response for phone number: ${phoneNumber}` +
            ` => code: ${responseBody['status']['code']}` +
            `, description: ${responseBody['status']['description']}`);
    } else {
        console.error("Unable to send voice. " + error);
    }
}

// Send voice request
client.verify.voice(voiceCallback, phoneNumber, optionalParams);

package com.telesign.enterprise.example.verify_voice;

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

import java.util.HashMap;

public class SendCustomVoiceCallInDifferentLanguage {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Your test phone number with no spaces or special characters goes here.";
        String language = "fr-FR";
        String ttsMessage = "Votre code de vérification Widgets 'n' More est $$CODE$$.";

        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);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

from __future__ import print_function
from telesignenterprise.verify import VerifyClient

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no spaces or special characters goes here."
language = "fr-FR"
tts_message = "Votre code de vérification Widgets 'n' More est $$CODE$$."

verify = VerifyClient(customer_id, api_key)
response = verify.voice(phone_number, language=language, tts_message=tts_message)

require 'telesignenterprise'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Your test phone number with no spaces or special characters goes here.'
language = 'fr-FR'
tts_message = 'Votre code de vérification Widgets \'n\' More est $$CODE$$.'

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, api_key)
response = verify_client.voice(phone_number, language: language, tts_message: tts_message)

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\enterprise\sdk\verify\VerifyClient;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no spaces or special characters goes here.";
$language = "fr-FR";
$tts_message = 'Votre code de vérification Widgets \'n\' More est $$CODE$$.';
$verify = new VerifyClient($customer_id, $api_key);
$response = $verify->voice($phone_number, [ "language" => $language, "tts_message" => $tts_message ]);

using System;
using System.Collections.Generic;
using Telesign;

namespace TelesignEnterprise.Example.VerifyVoice
{
    class SendCustomVoiceCallInDifferentLanguage
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "Your test phone number with no spaces or special characters goes here.";
            string language = "fr-FR";
            string ttsMessage = "Votre code de vérification Widgets 'n' More est $$CODE$$.";

            Dictionary<string, string> parameters = new Dictionary<string, string>();
            parameters.Add("language", language);
            parameters.Add("tts_message", ttsMessage);

            try
            {
                VerifyClient verifyClient = new VerifyClient(customerId, apiKey);
                RestClient.TelesignResponse telesignResponse = verifyClient.Voice(phoneNumber, parameters);
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

curl -X POST https://rest-ww.telesign.com/v1/verify/call -d phone_number=15555551212 -d language="fr-FR" -d tts_message="Votre code deverification est $$CODE$$" -u "CUSTOMER ID":"API KEY"

Sample code

var TeleSignSDK = require('telesignenterprisesdk');

console.log("## verify.voice ##");

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
const phoneNumber = "Your test phone number with no special characters or spaces goes here.";
const optionalParams = {verify_code: "32658"};

const client = new TeleSignSDK(customerId, apiKey);

// Callback handler for voice
function voiceCallback(error, responseBody) {
    if (error === null) {
        console.log(`Messaging response for messaging phone number: ${phoneNumber}` +
            ` => code: ${responseBody['status']['code']}` +
            `, description: ${responseBody['status']['description']}`);

        // Ask for user input
        prompt('Enter the verification code received:\n', function (input) {
            if (input === optionalParams['verify_code']) {
                console.log('Your code is correct.');
            } else {
                console.log('Your code is incorrect. input: ' + input + ", code: " + optionalParams['verify_code']);
            }
            process.exit();
        });

    } else {
        console.error("Unable to send voice call. " + error);
    }
}

// Method to handle user input
function prompt(question, callback) {
    const stdin = process.stdin,
        stdout = process.stdout;

    stdin.resume();
    stdout.write(question);

    stdin.once('data', function (data) {
        callback(data.toString().trim());
    });
}

// Send Voice request
client.verify.voice(voiceCallback, phoneNumber, optionalParams);

package com.telesign.enterprise.example.verify_voice;

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

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

public class SendVoiceCallWithVerificationCode {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "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();
        }
    }
}

from __future__ import print_function
from telesignenterprise.verify import VerifyClient
from telesign.util import random_with_n_digits

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no special characters or spaces goes here."
verify_code = random_with_n_digits(5)

verify = VerifyClient(customer_id, api_key)
response = verify.voice(phone_number, verify_code=verify_code)

user_entered_verify_code = raw_input("Please enter the verification code you were sent: ")

if verify_code == user_entered_verify_code.strip():
    print("Your code is correct.")
else:
    print("Your code is incorrect.")

require 'telesign'
require 'telesignenterprise'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Your test phone number with no special characters or spaces goes here.'
verify_code = Telesign::Util.random_with_n_digits(5)

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, api_key)
response = verify_client.voice(phone_number, verify_code: verify_code)

print 'Please enter the verification code you were sent: '
user_entered_verify_code = gets.strip

if verify_code == user_entered_verify_code
  puts 'Your code is correct.'
else
  puts 'Your code is incorrect.'
end

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\enterprise\sdk\verify\VerifyClient;
use function telesign\sdk\util\randomWithNDigits;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces goes here.";
$verify_code = randomWithNDigits(5);
$verify = new VerifyClient($customer_id, $api_key);
$response = $verify->voice($phone_number, [ "verify_code" => $verify_code ]);
echo "Please enter the verification code you were sent: ";
$user_entered_verify_code = trim(fgets(STDIN));
if ($verify_code == $user_entered_verify_code) {
  echo "Your code is correct.";
}
else {
  echo "Your code is incorrect.";
}

using System;
using System.Collections.Generic;
using Telesign;

namespace TelesignEnterprise.Example.VerifyVoice
{
    class SendVoiceCallWithVerificationCode
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "Your test phone number with no special characters or spaces goes here.";
            string verifyCode = "12345";

            Dictionary<string, string> parameters = new Dictionary<string, string>();
            parameters.Add("verify_code", verifyCode);

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

                Console.WriteLine("Please enter your verification code:");
                string code = Console.ReadLine().Trim();

                if (verifyCode == code)
                {
                    Console.WriteLine("Your code is correct.");
                }
                else
                {
                    Console.WriteLine("Your code is incorrect.");
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

curl -X POST https://rest-ww.telesign.com/v1/verify/call -d phone_number=15555551212 -d verify_code="12345" -u "CUSTOMER ID":"API KEY"

📘NOTE:

Before you begin

Install the SDK

Send a voice message with a verification code

Send a Voice Message with Verification Code in a Different Language

Sample code

📘
NOTE: