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.
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.
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
, 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. |
{
"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. |
{
"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. |
{
"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. |
{
"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. |
{
"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. |
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 |
{
"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:
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. |
[
{
"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. |
[
{
"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. |
[
{
"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 ofcall_answered
oranswered
)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. |
{
"method": "play",
"params": {
"url": "https://url-pointing-to-audio-file.com",
"collect_digits": {
"max": 5,
"timeout": 10000,
"inter_digit_timeout": 3000,
"terminators": "*"
}
}
}
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. |
{
"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. |
{
"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. |
{
"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. |
{
"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 ifdial_completed
has a status ofcall_answered
oranswered
)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. |
{
"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. |
[
{
"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. |