logo
API Reference
Tutorials
SDKs
Get Started
Sign In
Legal & Compliance
Support
No results found.
Authentication
Try the API Explorer
APIs
Get Started
Set up IVR
Make an Outbound Call
Receive an Inbound Call
Play Audio and Collect Digits
Play Audio with Multiple Files
Set Up a Call with Number Masking
Set up Click-to-Call
Perform a Cold Transfer
Survey After Call
Record a Call
Supported Standards and Codecs
Voice API Reference
Additional Features
SMPP Protocol
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

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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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.
external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO Your customer-generated ID for the original transaction this event is related to. If you didn’t include this in the original action, it’s not included in related events.
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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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.
params.external_id String An identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"		 NO A customer-generated ID for this transaction. The response echoes the value provided for this parameter and it’s also included in events from TeleSign related to this dial.
params.is_primary Boolean true false NO Whether you are using this service as your primary provider to initiate this call (true) or as a backup after your primary provider failed (false). We use this data to optimize call routing.
Example: dial Request Body
JSON
[
  {
    "method": "dial",
    "params": {
      "to": "15555551212",
      "caller_id_number": "15554441313",
      "send_dtmf": "6458",
      "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
      "is_primary": true
    }
  }
]

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 Create Masked Session for SMS or Voice for more details on creating a session.

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 or WAV file with at least an 8000 sample rate.

Example: https://yourdomain.com/file.wav		 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 or WAV file with at least an 8000 sample rate.

Example: https://yourdomain.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.
params.transcribe String A Boolean value formatted as a string.

Example: "true"		 NO Whether you want the service to generate a transcript for the recording ("true") or not ("false"). Defaults to "false".
params.language_code String One of the language codes listed on this page. Defaults to "en-US".

Example: "es-ES"		 NO A code indicating which language the service should expect during the recording; this is used to optimize the transcription.
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.