Voice - Actions
NOTE:
To add this product to your account, contact a Telesign expert.
This page lists and describes each action you can send to Telesign Voice. Actions are instructions to the service using the JSON-RPC format. These can be included in the payload of either your Engage API (Voice) request or your webhook endpoint response.
dial
Use this action to place an outbound call to a number you specify, or to bridge a third-party into an incoming call (incoming_call
event). If you try to use it to respond to any other event you will receive an error code stating that the call state is unsupported.
When making an outbound call, you can bridge it with the virtual number specified for the parameter 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. Contact 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
{
"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
{
"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
{
"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
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 | The URL for a 16-bit, 8KHz, .wav or .pcm audio file. Other file types are not supported. The file must be mono channel; audio in stereo is not supported. 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 used by the service as a terminator for the end user's input. Only one character can serve as a potential terminator. A terminator will not be returned if the optional detect_speech parameter is used. |
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.detect_speech | Object | {...} | NO | Contains properties related to speech recognition for user input. Contact Telesign Customer Support to enable this feature. |
params.detect_speech.language | String | One of the language codes for this feature. Defaults to en-US . | NO | The language to use for voice recognition. |
params.detect_speech.max_speech_duration | Integer | Defaults to 5000 . The minimum value is 1000 and the maximum value is 3000 . | NO | The length of time the end user can speak, measured in ms. |
params.detect_speech.timeout | Integer | Defaults to 5000 . The minimum value is 1000 and the maximum value is 5000 . | NO | The length of time measured in ms, starting after the audio file finishes playback, after which the service stops waiting for the end user to speak or enter digits. |
params.detect_speech.inter_speech_timeout | Integer | Defaults to 2000 . The minimum value is 1000 and the maximum value is 5000 . | NO | The length of time in ms, starting after the last word spoken by the end user, after which the service stops waiting for additional speech from the end user. |
Example: play request body
{
"method": "play",
"params": {
"url": "https://url-pointing-to-audio-file.com",
"collect_digits": {
"max": 5,
"timeout": 10000,
"inter_digit_timeout": 3000,
"terminators": "*"
}
}
}
NOTE:
You can use a higher sampling frequency than 8KHz, but we do not recommend doing so, as it wastes bandwidth.
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 ofcall_answered
oranswered
)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 | The URL for a 16-bit, 8KHz, .wav or .pcm audio file. Other file types are not supported. The file must be mono channel; audio in stereo is not supported. 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
{
"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"
]
}
}
NOTE:
You can use a higher sampling frequency than 8KHz, but we do not recommend doing so, as it wastes bandwidth.
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
{
"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
{
"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
{
"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
{
"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
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 Voice - Supported languages for text-to-speech table. | 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. | collect_digits |
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. Only one character can serve as a potential terminator. A terminator will not be returned if the optional detect_speech parameter is used. | |
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.detect_speech | Object | {...} | NO | Contains properties related to speech recognition for user input. Contact Telesign Customer Support to enable this feature. | |
params.detect_speech.language | String | One of the language codes for this feature. Defaults to en-US . | NO | The language to use for voice recognition. | |
params.detect_speech.max_speech_duration | Integer | Defaults to 5000 . The minimum value is 1000 and the maximum value is 3000 . | NO | The length of time the end user can speak, measured in ms. | |
params.detect_speech.timeout | Integer | Defaults to 5000 . The minimum value is 1000 and the maximum value is 5000 . | NO | The length of time measured in ms, starting after the audio file finishes playback, after which the service stops waiting for the end user to speak or enter digits. | |
params.detect_speech.inter_speech_timeout | Integer | Defaults to 2000 . The minimum value is 1000 and the maximum value is 5000 . | NO | The length of time in ms, starting after the last word spoken by the end user, after which the service stops waiting for additional speech from the end user. |
Example: speak request body
{
"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
{
"method": "send_dtmf",
"params": {
"dtmf": "1ww23w4567890ABCD*#"
}
}
Updated 7 months ago