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.

ParameterTypeValuesRequired?Description
methodString"dial"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.caller_id_numberStringA phone number.

Example: "15555551212"
YESThis 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_durationStringA number of seconds.

Example: "600"
NOSet 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_dtmfStringOne 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"
NODigits 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.toStringA phone number

Example: "15554441313"
YESThis is the number Telesign dials out to. Must be a valid phone number.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOA 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_primaryBooleantrue falseNOWhether 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.

ParameterTypeValuesRequired?Description
methodString"dial_session"YESThe type for this action.
paramsObject{...}NOContains sub-properties associated with this action type.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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.

ParameterTypeValuesRequired?Description
methodString"hangup"YESThe type for this action.
paramsObject{...}NOContains sub-properties associated with this action type.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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 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.

ParametersTypeValuesRequired?Description
methodString"play"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.urlStringThe 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
YESURL that points to the audio file you want to play.
params.collect_digitsObject{...}NOContains properties related to the collection of digits entered by the end user.
params.collect_digits.maxIntegerDefaults to 3.NOThe maximum number of digits to collect.
params.collect_digits.timeoutIntegerA span of time in ms. Defaults to 30000.NOThe 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_timeoutIntegerA span of time in ms. Defaults to the value of timeout; if that is not provided, defaults to 30000.NOThe 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.terminatorsStringSupported characters: 0-9, A-D, *, and #. Defaults to #.NOCharacters 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_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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_speechObject{...}NOContains properties related to speech recognition for user input. Contact Telesign Customer Support to enable this feature.
params.detect_speech.languageStringOne of the language codes for this feature. Defaults to en-US.NOThe language to use for voice recognition.
params.detect_speech.max_speech_durationIntegerDefaults to 5000. The minimum value is 1000 and the maximum value is 3000.NOThe length of time the end user can speak, measured in ms.
params.detect_speech.timeoutIntegerDefaults to 5000. The minimum value is 1000 and the maximum value is 5000.NOThe 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_timeoutIntegerDefaults to 2000. The minimum value is 1000 and the maximum value is 5000.NOThe 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 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.

ParametersTypeValuesRequired?Description
methodString"play"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.urlsArray[...]YESAn 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]StringThe 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_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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.

ParametersTypeValuesRequired?Description
methodString"record_pause"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session to pause recording for.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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.

ParametersTypeValuesRequired?Description
methodString"record_resume"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session to resume recording for.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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.

ParametersTypeValuesRequired?Description
methodString"record_start"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session to record.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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.transcribeStringA Boolean value formatted as a string.

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

Example: "es-ES"
NOA 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.

ParametersTypeValuesRequired?Description
methodString"record_stop"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session to stop recording.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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 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.

ParametersTypeValuesRequired?Description
methodString"play"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.ttsObject{...}YESContains sub-properties related to the text-to-speech message.
params.tts.messageStringA short message.

Example: "<speak>This message is in <prosody volume='loud'>English</prosody>.</speak>"
YESThe message that you want converted to audio.
params.tts.languageStringOne of the language tags included in the Voice - Supported languages for text-to-speech table.YESThe language for your message.
params.tts.typeStringtext, ssmlNOThe 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_digitsObject{...}NOContains properties related to the collection of digits entered by the end user.collect_digits
params.collect_digits.maxIntegerDefaults to 3.NOThe maximum number of digits to collect.
params.collect_digits.timeoutIntegerA span of time in ms. Defaults to 30000.NOThe 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_timeoutIntegerA span of time in ms. Defaults to the value of timeout; if that is not provided, defaults to 30000.NOThe 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.terminatorsStringSupported characters: 0-9, A-D, *, and #. Defaults to #.NOCharacters 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_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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_speechObject{...}NOContains properties related to speech recognition for user input. Contact Telesign Customer Support to enable this feature.
params.detect_speech.languageStringOne of the language codes for this feature. Defaults to en-US.NOThe language to use for voice recognition.
params.detect_speech.max_speech_durationIntegerDefaults to 5000. The minimum value is 1000 and the maximum value is 3000.NOThe length of time the end user can speak, measured in ms.
params.detect_speech.timeoutIntegerDefaults to 5000. The minimum value is 1000 and the maximum value is 5000.NOThe 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_timeoutIntegerDefaults to 2000. The minimum value is 1000 and the maximum value is 5000.NOThe 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.

ParametersTypeValuesRequired?Description
methodString"send_dtmf"YESThe type for this action.
paramsObject{...}YESContains sub-properties associated with this action type.
params.dtmfStringOne 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*#"
YESDigits to enter into the call.
params.event_urlStringAn HTTPS URL with a valid domain name (not just an IP). Query parameters can be included.

Example: "https://my-event-url.com"
NOThe 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*#"
  }
}