logo
API Reference
Tutorials
SDKs
Legacy
Legal & Compliance
Support
No results found.
Authentication
Try the API Explorer
Get Started
Set up IVR
Make an Outbound Call
Receive an Inbound Call
Send a TTS Message and Collect Digits
Stream Audio and Collect Digits
Set up Anonymous 2-Way Voice
Set up Click-to-Call
Perform a Cold Transfer
Survey After Call
Learn Supported Standards and Codecs
Voice API Reference
Customer Action API Reference
Call Query API Reference
Transaction Callback Service
Inbound SMS
URL Shortener
Codes, Languages, and Time Zones
Understand TeleSign Status and Error Codes
All Status and Error Codes
Want to provide feedback?

Write to docs@telesign.com.

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by navigating to our Voice API signup page.

Voice API Reference

This page provides details about the TeleSign Voice API. You can read about this API in the following sections:

General Information

All requests submitted for this API:

  • Can be authenticated with basic authentication.
  • Use https://rest-ww.telesign.com/v2/voice as the base endpoint.
  • Are formatted using JSON-RPC.
  • Accept only UTF-8 encoded unicode characters as inputs.

You must create a customer event URL on your server and provide it to TeleSign. This is where TeleSign will post information about calls and the status of requests you send to the Voice API.

Set up the Customer Event URL

TeleSign’s Voice API requires a customer event URL. When you send a request asking TeleSign to do something, TeleSign responds with the outcome of the event or a request for what to do by posting to your customer event URL on your server.

To set one up, do the following:

  1. Create a private URL on your web server for receiving notifications about events from TeleSign. The URL must:
    • Have a valid Domain Name Service address (no IP address)
    • Use HTTPS protocol
    • Use certificate signed by a valid certificate authority
    • Accept Basic Authorization headers to protect the endpoint from outside access
    • Be hosted at the exact URL you give to TeleSign (it will not work if TeleSign does not have the exact URL)
  2. Provide your Customer Success Manager (CSM) with your private URL.
  3. Allow 1 business day for setup to be completed.
  4. You will receive notifications of events for the Voice API at this URL.

An easy way to test is to try to make an outbound call to a phone number you have access to and can receive a call at. Receive the call, and then check to see if you are getting notifications about the call at the URL you provided. You can learn about making an outbound call on the Make an Outbound Call page.

Be aware that you can also choose to turn off receiving events by talking to your Customer Success Manager. You can use the Customer Action API Reference and the Call Query API Reference to take action on calls instead.

Voice API Structure

Voice has two kinds of methods:

  • Event - Events are things that occur that TeleSign informs you of through the API. For example, TeleSign informs you that there is an incoming call. You would then use an action to tell TeleSign how to handle the call.
  • Action - You tell TeleSign what to do, usually in response to an event, but you could request the action of dialing to start a new call. An example of an action would be if you are notified by an event that an end user is calling, you can request the action of answering the call. TeleSign would then answer the call, and inform you of that event (answering the call).

Event

After successfully completing authentication (you must check that TeleSign’s credentials match the credentials assigned to you) TeleSign can send you event information in response to your actions or if something is incoming like a call. Events occur as POST requests from TeleSign when a call is incoming or ending. All Event requests from TeleSign are POST requests that TeleSign posts to the customer event URL you provide. Each type of request is described by the kind of event it is, either incoming or ending. All requests from TeleSign are built from a general ‘Base Event’ structure.

Base Event Structure

All requests from TeleSign are POST requests with the same basic structure called a ‘Base Event.’

Each Base Event has two parameters:

Parameter Type Values Required Description
event String For example incoming_call, hangup YES A value representing the specific event types, either incoming call, or call ended.
data Dictionary, List {} YES A dictionary of key/value pairs that depend on the event type.
reference_id String “BC96D7B0D1800164898350B4E71B005C” Yes This is a TeleSign reference ID. This uniquely identifies the session.

The values in the data parameter will change based on the type of event specified by the event parameter.

Incoming Call

You can respond to incoming_call with hangup, speak, play, or dial.

When a call comes in to TeleSign and TeleSign passes the call information to you, it is refered to as an incoming call event. The structure matches the Base Event and the method is incoming_call. Inside the params object you will find the following parameters:

Parameters Type Required Description
reference_id string YES A unique, TeleSign generated identifier for the session.
data list of dictionaries YES A list of dictionaries.
POST Request for incoming_call
{
  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
        "to": "15555551212 - example only",
        "from": "15558675309 - example only",
      }
}

Dial Completed

You can only respond to dial with speak, play, or hangup.

This event occurs when the call is answered. The data dictionary is populated with the following parameters:

Parameters Type Values Required Description
to String 15558675309 YES Number the call is being made to.
from String 15555551212 YES Number the call is being made from.
status String answered, failed YES
Answered Event
{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "from": "15555551212 - example only",
    "to": "15558675309 - example only",
    "status": "answered"
  }
}

Play Completed

You can only respond to play_completed with speak, play, or hangup.

The play_completed event is for situations where the audio in the file you pointed to using the play action completes. If the end user presses a number in the middle of playing the audio file, it will stop the audio and register as play_completed.

Parameters Type Values Required Description
to String 15558675309 YES Number the call is being made to.
from String 15555551212 YES Number the call is being made from.
status String playback_successful, playback_failed, digit_collection_timeout YES
collected_digits String 923 YES
Play Completed Event
{
  "event": "play_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212 - example only",
    "to": "15558675309 - example only",
    "status": "playback_successful",
    "collected_digits": "923"
  }
}

Speak Completed

You can only respond to speak_completed with speak, play, or hangup.

This event is for situations where a text-to-speech message you created was played for the end user, and the message completes. If the end user presses a number in the middle of your text-to-speech message, the message stops and it will be registered as a completion. The data parameter will contain the following parameters:

Parameters Type Values Required Description
to String 15558675309 YES Number the call is being made to.
from String 15555551212 YES Number the call is being made from.
status String speak_successful, speak_failed, digit_collection_timeout YES
collected_digits String 923 YES
Speak Completed Event
{
  "event": "speak_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "from": "15555551212 - example only",
    "to": "15558675309 - example only",
    "status": "speak_successful",
    "collected_digits": "923"
  }
}

Call Completed

This event occurs when the end user hangs up. You will be notified of call completion, and no further call flow will be processed.

Parameters Type Values Required Description
to String 15558675309 YES Number the call is being made to.
from String 15555551212 YES Number the call is being made from.
direction String “inbound” or “outbound” YES A string describing whether the call was incoming to you, or outgoing from you.
status String hangup YES
created_on_utc String “2018-01-09T19:02:04.898803” YES ISO 8601 formatted timestamp showing when the call was created.
answered_on_utc String “2018-01-09T19:02:04.898803” YES ISO 8601 formatted timestamp showing when the call was answered.
ended_on_utc String “2018-01-09T19:02:04.898803” YES ISO 8601 formatted timestamp showing when the call ended.
duration Integer 6 YES Air time or billable time you are charged for.
audio_recording_file_name String “dfb2c74f-68b5-4039-9bbc-e8e32ae937c9.wav” YES If you specified that you wanted to record the call, the name of the file with your recording comes back here. Otherwise, this field is null.
Call Completed Example
{
  "event": "call_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "to": "15558675309 - example only",
    "from": "15555551212 - example only",
    "direction": "inbound",
    "created_on_utc": "2018-08-07T20:33:38.003718",
    "answered_on_utc": "2018-08-07T20:33:40.003718",
    "ended_on_utc": "2018-08-07T20:33:44.003718",
    "status": "hangup",
    "duration": 4,
    "audio_recording_file_name": "dfb2c74f-68b5-4039-9bbc-e8e32ae937c9.wav"
  }
}

Call Leg Completed

A call_leg_completed event is triggered when a child leg of a call hangs up. Think of legs of a call as when one caller is bridged to another. The first leg can be thought of as the ‘A leg.’ The A leg controls all the other legs of the call, if you hang up on this leg, the call ends. However, if any of the other legs hang up, the call can continue on through transfers or additional menus as needed.

Parameters Type Values Required Description
to String 15551234567 - example only YES Number where the call starts at
from String 12224395109 - example only YES Number where the call terminates
caller_id String 15552221414 - example only YES Must be a valid phone number
hangup_cause String ‘call_answered’, ‘call_cancelled’, ‘call_not_answered’, ‘line_busy’, ‘call_blocked_by_customer_request’, ‘call_blocked_by_telesign’ YES Enumeration

Action

You answer events with actions. You send the action you want to take in a response to TeleSign formatted in JSON-RPC. You can read the spec for JSON-RPC here. All responses should match the base response structure.

Base Action Structure

The general structure of each action has three parts:

Parameters Type Values Required? Description
jsonrpc string “2.0” YES This is the versioning for the JSON RPC specification.
method string “dial”, “hangup” YES This gives TeleSign instructions for what to do with the call.
params dictionary Depending on what method is selected, this will contain different parameters. YES The set of parameters to customize the execution of a method.

A list of available actions include:

  • dial - instruct TeleSign to place a call to the to number from caller_id_number.
  • hangup - instruct TeleSign to drop the incoming call.
  • play - instruct TeleSign to play an audio file.
  • speak - instruct TeleSign to play a text-to-speech message in the language you choose.

Dial

You can use dial to place a call to a number you specify. Otherwise you can only use dial with incoming_call. If you try to use it to respond to any other event you will receive a non 2xx HTTP status code stating that the call state is unsupported.

Use the dial action to instruct TeleSign to make an outbound call to the specified number for to and bridge it with the virtual number specified by caller_id_number.

Parameters Type Values Required? Validation Description
caller_id_number string “15555551212 - example only” YES You must purchase a number from TeleSign. Speak with your CSM to buy numbers. This is the number displayed as the caller_id.
to string “15554441313 - example only” YES Must be a valid phone number. This is the number TeleSign dials out to.
record_call boolean true / false NO Records the phone call. You will get the name of the file in the call_completed event in the audio_recording_file_name parameter and you can use this to retrieve your file.
Dial
[
  {
    "method": "dial",
    "params": {
      "to": "15555551212 - example only",
      "caller_id_number": "15554441313 - example only"
    }
  }
]

Hangup

The hangup action terminates any calls. If an end user calls a virtual number, but you do not recognize the end user’s phone number, you could issue a hangup command to reject the incoming call.

You cannot initiate a hangup, it must be in response to an event.

Play

The play action plays whatever audio file is stored at the URL you provide in your response. You cannot initiate a play command unless you receive one of the following responses from TeleSign:

  • dial_completed - If dial_completed has a status of call_answered or answered you can respond with play.
  • speak_completed - If speak_completed is returned, you can respond with play.
  • play_completed - If play_completed is returned, you can respond with play.

If you try to use it to respond to any other event you will receive a non 2xx HTTP status code stating that the call state is unsupported.

Here is how the play action is structured:

Parameters Type Values Required? Validation Description
url string https://url-pointing-to-audio-file.com YES The file you point to must be 16-bit PCM with at least an 8000 sample rate This is the url that points to the audio file you want to play.
collect_digits dictionary {max} You can optionally include max, an integer which lets you set the maximum number of digits to collect from the end user. If you do not use max, the default is 3 digits. NO

Here is an example of the play action being used with its required parameter:

Play Action
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com"
  }
}

Here is an example of the play action being used with the optional collect_digits parameter and max parameter:

Play Action with Collect Digits Feature
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
    }
  }
}

Speak

The speak action lets you create a text-to-speech message in the language of your choice and play that message for an end user. As with the play action, you can collect digits.

You cannot initiate a speak command unless you receive one of the following responses from TeleSign:

  • dial_completed - If dial_completed has a status of call_answered or answered you can respond with speak.
  • speak_completed - If speak_completed is returned, you can respond with speak.
  • play_completed - If play_completed is returned, you can respond with speak.

If you try to use it to respond to any other event you will receive a non 2xx HTTP status code stating that the call state is unsupported.

Here is how the speak action is structured:

Parameters Type Values Required? Description
tts dictionary {} YES {“message”:“This is a message”} You use this parameter to include the message to be converted to audio. Example: {“message”:“This message is in English.”, “language”:“en-US”}. You use this parameter to specify what language your message is in. Example: ‘en-us’. Both of these options are strings and required.
collect_digits dictionary {} NO {max} You can optionally include max, an integer which lets you set the maximum number of digits to collect from the end user.
Example of TTS Speak Command
{
  "jsonrpc": "2.0",
  "method": "speak",
  "params": {
    "tts": {
      "message": "Press 1 for your account balance. Press 2 to speak with a customer service representative.",
      "language": "en-US"
    },
    "collect_digits": {
      "max": 1
    }
  }
}

Supported Languages for Text-to-Speech

Some text-to-speech voices are male and some are female. What TeleSign offers is noted next to each language.

Language TTS Tag Male Voice Female Voice
Chinese, Mandarin cmn-CN x
Danish da-DK x
Dutch nl-NL x
English, Australian en-AU x
English, British en-GB x
English, Indian en-IN x
English, US en-US x
English, Welsh en-GB-WLS x
French fr-FR x
French Canadian fr-CA x
German de-DE x
Hindi hi-IN x
Icelandic is-IS x
Italian it-IT x
Japanese ja-JP x
Korean ko-KR x
Norweigan nb-NO x
Polish pl-PL x
Portuguese, Brazilian pt-BR x
Portuguese, European pt-PT x
Romanian ro-RO x
Russian ru-RU x
Spanish, European es-ES x
Spanish, US es-US x
Swedish sv-SE x
Turkish tr-TR x
Welsh cy-GB x