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.

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.

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.

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.

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.

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.

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.

Example: record_resume request body

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

record_start

Use this action to begin recording a call.

Example: record_start request body

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

record_stop

Use this action to stop recording a call.

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.

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.

send_dtmf request body

{
  "method": "send_dtmf",
  "params": {
    "dtmf": "1ww23w4567890ABCD*#"
  }
}