Additional Features

Transaction Callback Service

Inbound SMS

URL Shortener

Codes and Shared Info Across APIs

Codes, Languages, and Time Zones

Understand TeleSign Status and Error Codes

All Status and Error Codes

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by contacting our experts.

Voice API Reference

This page explains how to use the TeleSign Voice API solution.

Contents of this page

Supported Codecs
Components
Customer Event URL
- Set up the Customer Event URL
- Testing
- Events
  - incoming_call
  - dial_completed
  - dial_session_completed
  - play_completed
  - play_multiple_completed
  - speak_completed
  - call_completed
  - send_dtmf_completed
Voice API
- General Requirements
- Actions
  - dial
  - dial_session
  - hangup
  - play
  - play_multiple
  - record_pause
  - record_resume
  - record_start
  - record_stop
  - speak
  - send_dtmf
- Supported Languages for Text-to-Speech
- Status and Error Codes

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:

Customer Event URL: Use one or more of these to receive events from TeleSign notifying you that something occurred, like an incoming call.
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.

Customer Event URL

You set up and control a notification service, using it to receive events from TeleSign at one or more customer event URLs.

Set Up the Customer Event URL

This service should:

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.

Once you have set up this service, send the customer event URL to our Customer Support Team. If you plan to use multiple customer event URLs, send us the customer event URL you want to serve as the default. You can pass an alternate customer event URL in any of your requests to the Voice API, overriding the default for the duration of that phone call.

After one business day, 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 to your customer event URL. 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,play_multiple, 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, play_multiple, 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, play_multiple, 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#"
  }
}

play_multiple_completed

The service sends this event when playback of the audio files you requested using the play_multiple 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, play_multiple, or hangup.

Parameter	Type	Values	Required?	Description
event	String	`"play_multiple_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"`	YES	a quick description of why play completed

Example: play_multiple_completed Request Body

JSON

{
  "event": "play_multiple_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "playback_successful"
  }
}

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, play_multiple, 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"
  }
}

Voice API

Requests to the Voice API are called actions. Use these 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. This must either be the `from` number from an `incoming_call` event (when bridging a call) or a number purchased from TeleSign. Speak with our Customer Support Team to buy numbers.
params.max_call_duration	String	A number of seconds. Example: `"600"`	NO	Set the maximum call duration, overriding the default of 14,400 seconds for the duration of this call. You cannot set a call duration higher than the default.
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. Common uses for this feature include: • Dialing a number with an extension, by entering the extension into the call after the main number is dialed. • Entering a conference code to enter a conference 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
play_multiple_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": "*"
    }
  }
}

play_multiple

This action plays a series of audio files to an end user. You can initiate a play_multiple 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
play_multiple_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.urls	Array	`[...]`	YES	An array of URLs that each point to one of the audio files you want to play. The order of the array elements determines the order the audio files are played in.
params.urls[n]	String	URL for a 16-bit PCM with at least an 8000 sample rate. Example: `https://url-pointing-to-audio-file.com/file1.wav`	YES (at least one element must be included in the array)	URL that points to one of the audio files you want to play.
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_multiple",
  "params": {
    "urls": [
      "https://url-pointing-to-audio-file.com/file1.wav",
      "https://url-pointing-to-audio-file.com/file2.wav",
      "https://url-pointing-to-audio-file.com/file3.wav"
    ]
  }
}

record_pause

Use this action to pause a recording that you have started.

Parameters	Type	Values	Required?	Description
method	String	`"record_pause"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session to pause recording for.
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: record_pause Request Body

JSON

{
  "method": "record_pause",
  "params": {
    "reference_id": "BC96D7B0D1800164898350B4E71B005C"
  }
}

record_resume

Use this action to resume a recording that you have paused.

Parameters	Type	Values	Required?	Description
method	String	`"record_resume"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session to resume recording for.
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: record_resume Request Body

JSON

{
  "method": "record_resume",
  "params": {
    "reference_id": "BC96D7B0D1800164898350B4E71B005C"
  }
}

record_start

Use this action to begin recording a call.

Parameters	Type	Values	Required?	Description
method	String	`"record_start"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session to record.
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: record_start Request Body

JSON

{
  "method": "record_start",
  "params": {
    "reference_id": "BC96D7B0D1800164898350B4E71B005C"
  }
}

record_stop

Use this action to stop recording a call.

Parameters	Type	Values	Required?	Description
method	String	`"record_stop"`	YES	The type for this action.
params	Object	`{...}`	YES	Contains sub-properties associated with this action type.
params.reference_id	String	A 32-digit hex value. Example: `"BC96D7B0D1800164898350B4E71B005C"`	YES	This is a TeleSign reference ID. This uniquely identifies the session to stop recording.
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: record_stop Request Body

JSON

{
  "method": "record_stop",
  "params": {
    "reference_id": "BC96D7B0D1800164898350B4E71B005C"
  }
}

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
play_multiple_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

Status and Error Codes

Below are the meanings for some HTTP status codes and error strings specific to this API.

Status Code	Associated Text String	Description
200	`premium_to_number_rejected`	Phone number (`to`) in the request has the unsupported number type “premium”. Action rejected.
200	`to_number_blocked_by_country`	Phone number (`to`) in the request is blocked based on its country of origin. Blocked countries can be specified either by you in the customer portal, or by TeleSign. Action rejected.
200	`to_number_blocked_by_customer`	Phone number (`to`) in the request is on the blocked list in the customer portal. Action rejected.
200	`to_number_blocked_by_telesign`	Phone number (`to`) in the request is blocked by TeleSign for all requests. Action rejected.
400	`caller_id_number_not_owned`	Virtual number (`caller_id_number`) in the request is not owned by you. Action rejected.
400	`caller_id_number_not_provided`	Request does not include a virtual number (`caller_id_number`). Action rejected.
400	`invalid_phone_number`	Phone number (`to`) in the request is invalid. Action rejected.
400	`to_number_not_provided`	Request does not include a phone number (`to`). Action rejected.
400	`unsupported_call_state`	Action in the request is not supported for current call state, or not supported at all for this event. Action rejected.
401	`credentials_not_provided`	Customer ID and/or API key missing from the authorization header of the request. Action rejected.
401	`not_authorized`	Could not authenticate with the Customer ID and API key in the authorization header of the request. Action rejected.
429	`rate_limit_exceeded`	Account has exceeded rate limit for either outbound or inbound requests. Action rejected.
5XX	various	Other failure type. Contact our Customer Support Team for assistance.