Voice - Events

📘

NOTE:

To add this product to your account, contact a Telesign expert.

This page lists and describes each event returned by Telesign Voice. Events are webhook notifications sent from Voice to your specified endpoint.

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.

Example: incoming_call request body

{
  "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.

Example: dial_completed request body

{
  "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.

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.

Example: play_completed request body

{
  "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.

Example: play_multiple_completed request body

{
  "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.

Example: speak_completed request body

{
  "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.

Example: call_completed request body

{
  "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.

🚧

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.

Example: send_dtmf_completed Request Body

{
  "event": "send_dtmf_completed",
  "reference_id": "BC96D7B0D1800164898350B4E71B005C",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "data": {
    "to": "15558675309",
    "from": "15555551212",
    "status": "send_dtmf_success"
  }
}