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-api.telesign.com"; // Todo: Enterprise customer, change this!
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.";
const message = "You're scheduled for a dentist appointment at 2:30PM.";
const messageType = "ARN";


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

This quick start describes how to use TeleSign SDKs to send a voice message. You can use this to send alerts, reminders, and notifications for a variety of situations such as:

  • Weather updates
  • Status of a package being delivered
  • Reminder for appointments or events
  • A notification about a special offer or promotion
  • Notifications about a change in status to an account, for example to let someone know their password changed

This quick start includes the following sections:

Requirements

For this quick start, the following is required:

  • customer ID - obtain from your account by logging in to portal.telesign.com (referred to as customer_id / customerId in this document)
  • API key - obtain from your account by logging in to portal.telesign.com (referred to as api_key / apiKey in this document)
  • SDK - Access to TeleSign’s GitHub repository for your selected language:
  • Language Version
    • Node.js - 6+
    • Java - 7+
    • Python - 2.7+
    • Ruby - 2+
    • PHP - 5.6+
    • C# - 4.5+
  • Verified Phone Number - To use TeleSign’s free trial, you must verify a phone number before using it
NOTE:

If you do not have a customer ID, sign up for TeleSign’s Free Trial.

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

This section explains how to send a voice message using the Voice API. The sample code provided earlier is 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 the text-to-speech message you specify with the message type that you specify. The steps below explain the code sample 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.
    • customer_id / customerId - Your TeleSign assigned customer ID, available in your account information in the portal.
    • api_key / apiKey - Your TeleSign assigned API key, available in your account information in the portal.
    • phone_number / phoneNumber - 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. The phone number given must include the country code (and the area code for the US). 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 - Provide your message as a string.
    • message_type / messageType - 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.
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-api.telesign.com"; // Todo: Enterprise customer, change this!
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.";
const message = "You're scheduled for a dentist appointment at 2:30PM.";
const messageType = "ARN";
  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/telesignResponse. For node.js, you set up a console, declare a function to handle responses, and then instantiate a VoiceClient object.
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. You should receive a phone call containing a text-to-speech voice message you specified at the phone number you specified. You can examine the result of your phone call by looking at the contents of response/telesignResponse.

Send a Voice Message in a Different Language

You can send a voice message in a different language easily. Here is a code sample that will send a message in a different language:

var TeleSignSDK = require('telesignsdk');

const customerId = "customer_id"; // Todo: find in portal.telesign.com
const apiKey = "dGVzdCBhcGkga2V5IGZvciBzZGsgZXhhbXBsZXM="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.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 message = "N'oubliez pas d'appeler votre mère pour son anniversaire demain.";
const messageType = "ARN";
const languageCode = "f-FR-fr";

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, voice=languageCode);

The main difference in the code happens in step 3 from the Send a Voice Message section. You include a line indicating what language you want your message to be spoken in. The piece of code is presented the same as step 3 with the inclusion of the new code here:

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

Code it Without the SDK

If you want to write all your own code, you must handle authentication yourself. You’ll need the following documents: