Voice API Reference

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

General Information
Set up the Customer Event URL
Voice API Structure
- Event
  - Base Event Structure
  - Incoming Call
  - Dial Completed
  - Play Completed
  - Speak Completed
  - Call Completed
- Action
  - Base Action Structure
  - Dial
  - Hangup
  - Play
  - Speak
Supported Languages for Text-to-Speech

General Information

All requests submitted for this API:

Can be authenticated with basic authentication.
Use https://rest.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:

Create a private URL on your web server for receiving notifications about events from TeleSign.
Provide your Technical Account Manager (TAM) with your private URL.
Allow 1 business day for setup to be completed.
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.

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",
        "from": "+15558675309",
      }
}

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",
    "to": "15558675309",
    "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",
    "to": "15558675309",
    "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",
    "to": "15558675309",
    "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",
    "from": "15555551212",
    "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	YES	Number where the call starts at
from	String	12224395109	YES	Number where the call terminates
caller_id	String	15552221414	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”	YES	You must purchase a number from TeleSign. Speak with your TAM to buy numbers.	This is the number displayed as the caller_id.
to	string	“+15554441313”	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",
      "caller_id_number": "+15554441313"
    }
  }
]

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.

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