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 explains how to use the TeleSign Voice API solution.

Contents of this page

Supported Codecs
Components
Notification Service
- Set up the Customer Event URL
- Testing
- Events
  - incoming_call
  - dial_completed
  - dial_session_completed
  - play_completed
  - speak_completed
  - call_completed
  - send_dtmf_completed
TeleSign Voice API
- General Requirements
- Actions
  - dial
  - dial_session
  - hangup
  - play
  - speak
  - send_dtmf
- Supported Languages for Text-to-Speech

Supported Codecs

Use only codecs and standards for audio files supported by the Voice API. See Supported Standards and Codecs for more details.

Components

This solution has two components:

Notification Service: Use this to get notification from TeleSign that something occurred, like an incoming call. It may also ask you what to do in response.
TeleSign Voice API: Use this to send requests to TeleSign, usually in response to an event or to start a new call. Requests you make to this service are called actions.

Notification Service

You must choose one of two options to get call info notifications from TeleSign:

Create one or more customer event URLs where we can send you notifications. Requests we make to this service are called events. You set up and control this service.
Use the Customer Action API and the Call Query API to proactively retrieve notifications.

The setup process described here assumes the first option, but the second one is also supported. Even after setting up the solution with the first option, you can still turn off receiving events and switch to the second option; ask our Customer Support Team if you want to make that switch.

Set Up a Customer Event URL

To set up a customer event URL for your notification service, do the following:

Configure a URL for receiving events from TeleSign. This URL must:
- Have a valid DNS name (can’t just be an IP address)
- Require the HTTPS protocol
- Require a certificate signed by a valid certificate authority
- (OPTIONAL) Use Digest authentication.
Send this URL to our Customer Support Team.
Allow one business day for setup to be completed.

Once setup is complete on our side, we will begin sending events to this URL.

Caution

Double-check that the customer event URL is accurate when you send it to TeleSign! If you provide us the wrong URL, we will not be able to send you any events.

Note

Authentication to validate the requests coming in to your server from TeleSign is not required. We do recommend however that you use Digest authentication to prevent malicious parties from contacting your server.

Testing

An easy way to test your setup is to try to make an outbound call to a phone number you have access to, and at which you can receive a call. 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.

Events

incoming_call

When a call comes in to TeleSign, the service uses this event to pass the call information to you.

Supported responses are hangup, speak, play, or dial.

Parameter	Type	Values	Required?	Description
event	String	`"incoming_call"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	A phone number.	YES	Your virtual phone number that the end user is calling.
data.from	String	A phone number.	YES	The caller ID of the end user calling you.

Example: incoming_call Request Body

JSON

{
  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
    "to": "15558675309",
    "from": "15555551212"
  }
}

dial_completed

The service sends this event when the call is answered or fails.

You can respond with speak, play, hangup, or send_dtmf.

Parameter	Type	Values	Required	Description
event	String	`"dial_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	A phone number. Example: `"15558675309"`	YES	Number the call is being made to.
data.from	String	A phone number. Example: `"15555551212"`	YES	Number the call is being made from.
data.status	String	`"answered"`, `"failed"`	YES	Whether the call was answered or failed.

Example: dial_completed Request Body

JSON

{
  "event": "dial_completed",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
    "to": "15558675309",
    "from": "15555551212",
    "status": "answered"
  }
}

dial_session_completed

The service sends this event if we were unable to retrieve the session you requested in a dial_session action.

Parameter	Type	Values	Required?	Description
event	String	`"dial_session_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	A phone number. Example: `"15558675309"`	YES	the value of the “to” parameter in your dial-session request
data.from	String	A phone number. Example: `"15555551212"`	YES	the value of the “from” parameter in your dial-session request
data.status	String	A snake-case message. Example: `"session_not_found"`	YES	a quick description of why retrieval failed

play_completed

The service sends this event when playback of the audio file you requested using the play action completes for an end user. For example, if the end user presses a number in the middle of playback, the audio stops and this event is triggered.

Supported responses are speak, play, or hangup.

Parameter	Type	Values	Required?	Description
event	String	`"play_completed"`	YES	The type for this event.
reference_id	String	a 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	a phone number (ex: `"15558675309"`)	YES	Number the call is being made to.
data.from	String	a phone number (ex: `"15555551212"`)	YES	Number the call is being made from.
data.status	String	`"playback_successful"`, `"playback_failed"`, `"digit_collection_timeout"`	YES	a quick description of why play completed
data.collected_digits	String	a set of dtmf digits. Example: `"923#"`	YES	Digits entered during the call, including the terminator used.

Example: play_completed Request Body

JSON

{
  "event": "play_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "playback_successful",
    "collected_digits": "923#"
  }
}

speak_completed

The service sends this event when a text-to-speech message you created was played for the end user, and the message completes. For example, if the end user presses a number while the message is in-progress being played, the audio stops and this event is triggered.

Supported responses are speak, play, or hangup.

Parameter	Type	Values	Required	Description
event	String	`"speak_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	a phone number. Example: `"15558675309"`	YES	Number the call is being made to.
data.from	String	a phone number. Example: `"15555551212"`	YES	Number the call is being made from.
data.status	String	`"speak_successful"`, `"speak_failed"`, `"digit_collection_timeout"`	YES	a quick description of why play completed
data.collected_digits	String	a set of dtmf digits. Example: `"923#"`	YES	Digits entered during the call, including the terminator used.

Example: speak_completed Request Body

JSON

{
  "event": "speak_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "speak_successful",
    "collected_digits": "923#"
  }
}

call_completed

The service sends this event when the end user hangs up. You will be notified of call completion, and no further call flow will be processed.

Parameter	Type	Values	Required?	Description
event	String	`"call_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	a phone number (ex: `"15558675309"`)	YES	Number the call is being made to.
data.from	String	a phone number (ex: `"15555551212"`)	YES	Number the call is being made from.
data.direction	String	`"inbound"` or `"outbound"`	YES	A string describing whether the call was incoming to you, or outgoing from you.
data.status	String	`"completed"`,`"busy"`,`"no_answer"`,`"call_failed"`	YES	a quick description of why the call completed
data.created_on_utc	String	a date-time (ex:`"2018-01-09T19:02:04.898803"`)	YES	ISO 8601 formatted timestamp showing when the call was created.
data.answered_on_utc	String	a date-time (ex:`"2018-01-09T19:02:04.898803"`)	YES	ISO 8601 formatted timestamp showing when the call was answered.
data.ended_on_utc	String	a date-time (ex:`"2018-01-09T19:02:04.898803"`)	YES	ISO 8601 formatted timestamp showing when the call ended.
data.duration	Integer	a span of time in seconds Example: `6`	YES	Air-time or billable time you are charged for.
data.session_info	Object	`{...}` or `{}`	YES	If a session was used for the call, contains additional properties with info about that session. Otherwise this object is empty.
data.session_info.session_legs	Array	an array of objects	NO	Contains an object with additional properties for each leg of the call. Only present when a session was used.
data.session_info.session_legs[n].phone_number	String	a phone number (ex: `"15558675309"`)	NO	The phone number used for the nth leg of the call. Only present when a session was used.
data.session_info.session_legs[n].virtual_number	String	a phone number (ex: `"15556714136"`)	NO	The assigned masking ID shown to the opposite party for the nth leg of the call. Only present when a session was used.
data.session_info.reference_id	String	a 32-digit hex value (ex: “C5B8F46B7D2C016C88308ABCE1D00169”)	NO	The unique ID of the session that was used in the transaction. Only present when a session was used.

Example: call_completed Request Body

JSON

{
  "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,
    "session_info": {
      "session_legs": [
        {
          "phone_number": "15555551212",
          "virtual_number": "15559752072"
        },
        {
          "phone_number": "15558675309",
          "virtual_number": "15556714136"
        }
      ],
      "reference_id": "RIYZZJCR285BTGZ7MQ2ZGPV8F9RX1LRH"
    }
  }
}

call_leg_completed

The service sends this event 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 is referred to 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.

Parameter	Type	Values	Required?	Description
event	String	`"call_leg_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	Yes	A TeleSign ID that uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	a phone number Example: `"15551234567"`	YES	Number where the call originates
data.from	String	a phone number Example: `"12224395109"`	YES	Number where the call terminates
data.caller_id	String	a phone number Example: `"1555222141"`	YES	Intermediate virtual number
data.hangup_cause	String	`"call_answered"`, `"call_cancelled"`, `"call_not_answered"`, `"line_busy"`, `"call_blocked_by_customer_request"`, `"call_blocked_by_telesign"`	YES	Why the call hung up.

Caution

Do not respond to the call_leg_completed event with dial_session; this action is not supported by the service and results in termination of the call.

send_dtmf_completed

The service sends this event in response to a send_dtmf action, to let you know its status.

Parameter	Type	Values	Required?	Description
event	String	`"send_dtmf_completed"`	YES	The type for this event.
reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session.
data	Object	`{...}`	YES	Contains sub-properties associated with this event type.
data.to	String	a phone number (ex: `"15558675309"`)	YES	Number the call is being made to.
data.from	String	a phone number (ex: `"15555551212"`)	YES	Number the call is being made from.
data.status	String	`"send_dtmf_success"`, `"send_dtmf_failed"`, `"invalid_dtmf"` (occurs when one of the digits in the request is not supported by the service)	YES	a quick description of what happened with your Send DTMF request

Example: send_dtmf_completed Request Body

JSON

{
  "event": "send_dtmf_completed",
  "reference_id": "BC96D7B0D1800164898350B4E71B005C",
  "data": {
    "to": "15558675309",
    "from": "15555551212",
    "status": "send_dtmf_success"
  }
}

TeleSign Voice API

Requests to the TeleSign Voice API are also called actions. Use actions to tell TeleSign what to do, usually in response to an event or to start a new call

General Requirements

You must observe these requirements for all requests to this API:

Authentication: Use Basic authentication
Endpoint: https://rest-ww.telesign.com/v2/voice
Encoding: UTF-8 encoded unicode characters
Request Body Format: JSON-RPC
Supported Methods: POST

Caution

Double-check that the customer event URL is accurate when you send it to TeleSign! If you provide us the wrong URL, we will not be able to send you any events.

Actions

You answer events with actions. After receving an event, you indicate the action you want to take in response by making a request to TeleSign.

For example, after getting an event indicating that an end user is calling, you can use an action to let TeleSign know you want to answer the call.

dial

Use this action to place an outbound call to a number you specify, or in response to the incoming_call event. 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.

When making an outbound call you can bridge it with the virtual number specified by caller_id_number.

Parameter	Type	Values	Required?	Description
method	String	`"dial"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.caller_id_number	String	a phone number. Example: `"15555551212"`	YES	This is the number displayed as the caller ID. You must purchase a number from TeleSign. Speak with our Customer Support Team to buy numbers.
params.send_dtmf	String	One or more supported DTMF digits (see Supported Standards and Codecs) formatted as one string. Supported digits are: `0`-`9`, `A`-`D`, `*`, and `#`. `w` characters can also be added in between digits to instruct the service to pause before entering the next digit into the call. Each `w` indicates a 0.5 second pause. Example: `"6458"`	NO	Digits to enter into the call.
params.to	String	A phone number Example: `"15554441313"`	YES	This is the number TeleSign dials out to. Must be a valid phone number.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

Example: dial Request Body

JSON

[
  {
    "method": "dial",
    "params": {
      "to": "15555551212",
      "caller_id_number": "15554441313",
      "send_dtmf": "6458"
    }
  }
]

dial_session

Use this action to connect a call using a session you previously created with TeleSign. If the session is retrieved successfully, the call is connected; if not, we send the dial_session_completed event to inform you of the failure. See also Set Up an Anonymous Voice Session for more details on creating a sesion.

Parameter	Type	Values	Required?	Description
method	String	`"dial_session"`	YES	The type for this action.
params	Object	`{...}`	NO	Contains sub-properties associated with this action type.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

Example: dial_session Request Body

JSON

[
  {
    "method": "dial_session"
  }
]

hangup

This action terminates any calls. If an end user calls your virtual number, but you do not recognize their phone number, you can use this action to reject the incoming call.

You can only request a hangup in response to an event.

Parameter	Type	Values	Required?	Description
method	String	`"hangup"`	YES	The type for this action.
params	Object	`{...}`	NO	Contains sub-properties associated with this action type.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

Example: hangup Request Body

JSON

[
  {
    "method": "hangup"
  }
]

play

This action plays an audio file to an end user. You can initiate a play command only if you receive one of the following events from TeleSign:

dial_completed (only if the event includes a status of call_answered or answered)
speak_completed
play_completed

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

Parameters	Type	Values	Required?	Description
method	String	`"play"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.url	String	URL for a 16-bit PCM with at least an 8000 sample rate. Example: `https://url-pointing-to-audio-file.com`	YES	URL that points to the audio file you want to play.
params.collect_digits	Object	`{...}`	NO	Contains properties related to the collection of digits entered by the end user.
params.collect_digits.max	Integer	Defaults to `3`.	NO	The maximum number of digits to collect.
params.collect_digits.timeout	Integer	A span of time in ms. Defaults to `30000`.	NO	The duration of the window, starting after the audio file finishes playback, at the end of which the service stops waiting for the first digit to be pressed and ends collection of digits.
params.collect_digits.inter_digit_timeout	Integer	A span of time in ms. Defaults to the value of `timeout`; if that is not provided, defaults to `30000`.	NO	The duration of the window, starting after the end user presses their most recent digit, at the end of which the service stops waiting for the next digit to be pressed and ends collection of any more digits. The window resets from the beginning after each new digit is pressed.
params.collect_digits.terminators	String	Supported characters: `0`-`9`, `A`-`D`, `*`, and `#`. Defaults to `#`.	NO	Characters to be used by the service as a terminator for the end user’s input. Each character serves independently as a potential terminator.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

Example: play Request Body

JSON

{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
      "timeout": 10000,
      "inter_digit_timeout": 3000,
      "terminators": "*"
    }
  }
}

speak

Use this action to play a text-to-speech (TTS) message in the language of your choice to an end user. As with the play action, you can collect digits.

Do not use this action unless you receive one of the following responses from TeleSign:

dial_completed (only if dial_completed has a status of call_answered or answered)
speak_completed
play_completed

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

Parameters	Type	Values	Required?	Description
method	String	`"play"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.tts	Object	`{...}`	YES	Contains sub-properties related to the text-to-speech message.
params.tts.message	String	A short message. Example: `"<speak>This message is in <prosody volume='loud'>English</prosody>.</speak>"`	YES	The message that you want converted to audio.
params.tts.language	String	One of the language tags included in the table Supported Languages for Text-to-Speech.	YES	The language for your message.
params.tts.type	String	`text`, `ssml`	NO	The content type of your message. Either plain text or speech synthesis markup language (SSML). See Using SSML for TTS for more details on that content type.
params.collect_digits	Object	`{...}`	NO	Contains properties related to the collection of digits entered by the end user.
params.collect_digits.max	Integer	Defaults to `3`.	NO	The maximum number of digits to collect.
params.collect_digits.timeout	Integer	A span of time in ms. Defaults to `30000`.	NO	The duration of the window, starting after the message finishes, at the end of which the service stops waiting for the first digit to be pressed and ends collection of digits.
params.collect_digits.inter_digit_timeout	Integer	A span of time in ms. Defaults to the value of `timeout`; if that is not provided, defaults to `30000`.	NO	The duration of the window, starting after the end user presses their most recent digit, at the end of which the service stops waiting for the next digit to be pressed and ends collection of any more digits. The window resets from the beginning after each new digit is pressed.
params.collect_digits.terminators	String	Supported characters: `0`-`9`, `A`-`D`, `*`, and `#`. Defaults to `#`.	NO	Characters to be used by the service as a terminator for the end user’s input. Each character serves independently as a potential terminator.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

Example: speak Request Body

JSON

{
  "method": "speak",
  "params": {
    "tts": {
      "message": "<speak>Press <prosody volume='loud'>1</prosody> for your account balance. Press <prosody volume='loud'>2</prosody> to speak with a customer service representative.</speak>",
      "language": "en-US",
      "type": "ssml"
    },
    "collect_digits": {
      "max": 1,
      "timeout": 10000,
      "inter_digit_timeout": 3000,
      "terminators": "*"
    }
  }
}

send_dtmf

Use this action to programmatically enter digits into a call. This affects call-flow logic just as if an end user had entered these digits.

Only use this action in response to a dial_completed event.

Parameters	Type	Values	Required?	Description
method	String	`"send_dtmf"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.dtmf	String	One or more supported DTMF digits (see Supported Standards and Codecs) formatted as one string. Supported digits are: `0`-`9`, `A`-`D`, ``, and `#`. `w` characters can also be added in between digits to instruct the service to pause before entering the next digit into the call. Each `w` indicates a 0.5 second pause. Example: `"1ww23w4567890ABCD#"`	YES	Digits to enter into the call.
params.event_url	String	An HTTPS URL with a valid domain name (not just an IP). Query parameters can be included. Example: `"https://my-event-url.com"`	NO	The customer event URL that you want TeleSign to send events to related to this request, for all actions for the duration of the call. This overrides the default customer event URL configured for your account.

send_dtmf Request Body

JSON

[
  {
    "method": "send_dtmf",
    "params": {
      "dtmf": "1ww23w4567890ABCD*#"
    }
  }
]

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