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.

ParameterTypeValuesRequired?Description
eventString"incoming_call"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesThis is a Telesign reference ID. This uniquely identifies the session.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringA phone number.YESYour virtual phone number that the end user is calling.
data.fromStringA phone number.YESThe caller ID of the end user calling you.

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.

ParameterTypeValuesRequiredDescription
eventString"dial_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringA phone number.

Example: "15558675309"
YESNumber the call is being made to.
data.fromStringA phone number.

Example: "15555551212"
YESNumber the call is being made from.
data.statusString"answered", "failed"YESWhether the call was answered or failed.

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.

ParameterTypeValuesRequired?Description
eventString"dial_session_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringA phone number.

Example: "15558675309"
YESthe value of the "to" parameter in your dial-session request
data.fromStringA phone number.

Example: "15555551212"
YESthe value of the "from" parameter in your dial-session request
data.statusStringA snake-case message.

Example: "session_not_found"
YESa 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, play_multiple, or hangup.

ParameterTypeValuesRequired?Description
eventString"play_completed"YESThe type for this event.
reference_idStringa 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number
(ex: "15558675309")
YESNumber the call is being made to.
data.fromStringa phone number
(ex: "15555551212")
YESNumber the call is being made from.
data.statusString"playback_successful", "playback_failed", "digit_collection_timeout"YESa quick description of why play completed
data.collected_digitsStringa set of dtmf digits.

Example: "923#"
YESDigits entered during the call, including the terminator used.

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.

ParameterTypeValuesRequired?Description
eventString"play_multiple_completed"YESThe type for this event.
reference_idStringa 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number
(ex: "15558675309")
YESNumber the call is being made to.
data.fromStringa phone number
(ex: "15555551212")
YESNumber the call is being made from.
data.statusString"playback_successful", "playback_failed"YESa quick description of why play completed

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.

ParameterTypeValuesRequiredDescription
eventString"speak_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number.

Example: "15558675309"
YESNumber the call is being made to.
data.fromStringa phone number.

Example: "15555551212"
YESNumber the call is being made from.
data.statusString"speak_successful", "speak_failed", "digit_collection_timeout"YESa quick description of why play completed
data.collected_digitsStringa set of dtmf digits.

Example: "923#"
YESDigits entered during the call, including the terminator used.

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.

ParameterTypeValuesRequired?Description
eventString"call_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesThis is a Telesign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number
(ex: "15558675309")
YESNumber the call is being made to.
data.fromStringa phone number
(ex: "15555551212")
YESNumber the call is being made from.
data.directionString"inbound" or "outbound"YESA string describing whether the call was incoming to you, or outgoing from you.
data.statusString"completed","busy","no_answer","call_failed"YESa quick description of why the call completed
data.created_on_utcStringa date-time
(ex:"2018-01-09T19:02:04.898803")
YESISO 8601 formatted timestamp showing when the call was created.
data.answered_on_utcStringa date-time
(ex:"2018-01-09T19:02:04.898803")
YESISO 8601 formatted timestamp showing when the call was answered.
data.ended_on_utcStringa date-time
(ex:"2018-01-09T19:02:04.898803")
YESISO 8601 formatted timestamp showing when the call ended.
data.durationIntegera span of time in seconds

Example: 6
YESAir-time or billable time you are charged for.
data.session_infoObject{...} or {}YESIf a session was used for the call, contains additional properties with info about that session. Otherwise this object is empty.
data.session_info.session_legsArrayan array of objectsNOContains 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_numberStringa phone number
(ex: "15558675309")
NOThe phone number used for the nth leg of the call. Only present when a session was used.
data.session_info.session_legs[n].virtual_numberStringa phone number
(ex: "15556714136")
NOThe 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_idStringa 32-digit hex value
(ex: "C5B8F46B7D2C016C88308ABCE1D00169")
NOThe unique ID of the session that was used in the transaction. Only present when a session was used.

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.

ParameterTypeValuesRequired?Description
eventString"call_leg_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YesA Telesign ID that uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number

Example: "15551234567"
YESNumber where the call originates
data.fromStringa phone number

Example: "12224395109"
YESNumber where the call terminates
data.caller_idStringa phone number

Example: "1555222141"
YESIntermediate virtual number
data.hangup_causeString"call_answered", "call_cancelled", "call_not_answered", "line_busy", "call_blocked_by_customer_request", "call_blocked_by_telesign"YESWhy the call hung up.

🚧

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.

ParameterTypeValuesRequired?Description
eventString"send_dtmf_completed"YESThe type for this event.
reference_idStringA 32-digit hex value.

Example: "BC96D7B0D1800164898350B4E71B005C"
YESThis is a TeleSign reference ID. This uniquely identifies the session.
external_idStringAn identifier generated by you.

Example: "4142b474-d65d-4265-a5fa-a581b1fe6101"
NOYour customer-generated ID for the original transaction this event is related to. If you didn't include this in the original action, it's not included in related events.
dataObject{...}YESContains sub-properties associated with this event type.
data.toStringa phone number
(ex: "15558675309")
YESNumber the call is being made to.
data.fromStringa phone number
(ex: "15555551212")
YESNumber the call is being made from.
data.statusString"send_dtmf_success", "send_dtmf_failed", "invalid_dtmf" (occurs when one of the digits in the request is not supported by the service)YESa quick description of what happened with your Send DTMF request

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"
  }
}