Send a Voice Message with a Verification Code

var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-ww.telesign.com";
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces goes here.";
const messageType = "ARN";
const verifyCode = "32658";
const message = "Your code is " + verifyCode;

console.log("## VoiceClient.call ##");

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

client.voice.call(voiceCallback, phoneNumber, message, messageType);

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

prompt('Enter the verification code received:\n', function (input) {
    if (input === verifyCode) {
        console.log('Your code is correct.');
    } else {
        console.log('Your code is incorrect. input: ' + input + ", code: " + verifyCode);
    }
    process.exit();
});

This tutorial describes how to use TeleSign SDKs to send a custom voice message containing a verification code. This is great for a situation where you want to verify someone’s phone number, or provide two factor authentication (2FA). You can send a verification code to someone’s phone as an extra check before allowing them access to your website. You can also send a verification code to verify someone’s phone number, for example if they want a new account with you and you ask them to provide a phone number to send the verification code to.

This tutorial includes the following sections:

Requirements

For this tutorial, the following is required:

  • customer ID - obtain from your account by logging in to teleportal.telesign.com
  • API key - obtain from your account by logging in to teleportal.telesign.com
  • SDK - Access to TeleSign’s GitHub repository for your selected language (you must request access from your Technical Account Manager):
  • Language Version
    • Node.js - 6+
    • Java - 7+
    • Python - 2.7+
    • Ruby - 2+
    • PHP - 5.6+
    • C# - 4.5+

Install the SDK

  1. Obtain your customer ID and API key.
  2. Log in to GitHub and choose the SDK in your preferred language:
  3. Download or clone the repository. If you download it, extract the repository from the .ZIP file.
  4. To install the SDK for use, do the following:

Send a Voice Message with a Verification Code

This section explains how to send a voice message containing a verification code using the Voice API. The sample code is provided as a single block first, and then broken out into pieces and explained below.

In this code sample, you provide your customer ID and API key to authenticate yourself with TeleSign. Then you create a VoiceClient object and use the call method to place a voice call containing a text-to-speech message that includes a verification code and message that you specify. The steps below explain the code with more detail.

  1. 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('telesignsdk');
  1. Insert values for each of the items from customer_id through to message_type (through to restEndpoint for Java).
    • customer_id (customerId for Java/C#) - Your TeleSign assigned customer ID, available in your account information in the portal.
    • api_key (apiKey for Java/C#) - Your TeleSign assigned API key, available in your account information in the portal.
    • phone_number - The phone number you want to use for the example. 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). When you provide the number, it should be a string with no spaces or special characters. Include the complete number. For example, if you are doing a phone number for America, you would include the country code and the area code with the number. For example 16505551212.
    • message_type - Label the type of message you are sending. You have three choices (each is a string): OTP - One time passwords, ARN - Alerts, reminders, and notifications, and MKT - Marketing traffic.
    • restEndpoint - (For Java, you are defining a string with the value of the base endpoint.)

For node.js, you also define a verification code and insert it into your message in this step.

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-ww.telesign.com";
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces goes here.";
const messageType = "ARN";
const verifyCode = "32658";
const message = "Your code is " + verifyCode;
  1. Generate a random number to use as a verification code. For voice verification codes, TeleSign recommends limiting the code to five digits maximum so your end user can remember the code. Here you are generating a random five digit number.
NOTE:

For node.js and C# the code just assigns a five digit number.

//Step does not apply for node.js
  1. Insert your verification code into the text of your message that will be used to create the text-to-speech voice message.
//Step does not apply for node.js
  1. Instantiate a VoiceClient object and pass it your customer ID and API key. Place a call to the phone number containing the message and message type you provided. Store the response in response for Python/Ruby/PHP or telesignResponse for Java/C#. For node.js, use this step to create a console and declare a function that will handle the VoiceClient object you create.
console.log("## VoiceClient.call ##");

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

client.voice.call(voiceCallback, phoneNumber, message, messageType);
  1. Prompt for the verification code and enter the code you receive via voice message. You probably will set up the way you prompt the person differently, this is just to show you how it works.
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());
    });
}
  1. Check the code entered by the end user against the verification code you generated.
prompt('Enter the verification code received:\n', function (input) {
    if (input === verifyCode) {
        console.log('Your code is correct.');
    } else {
        console.log('Your code is incorrect. input: ' + input + ", code: " + verifyCode);
    }
    process.exit();
});
  1. If everything works, you should be able to generate and send a verification code via text-to-speech voice message using this code sample. When you receive the verification code, you are prompted to enter it. If you enter it correctly, you get a message back on your computer saying the code is correct. Otherwise you get a message saying the code is incorrect.

Code it Without the SDK

You can code without using the SDK by reviewing the following documents: