This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

Developers
Sign in
Create an AccountSign inQuestions on setup? Talk to our experts

Call Answered Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id Unique call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
state 'answered'

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "call_answered",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "state": "answered"
    }
}

Call Bridged Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
state 'bridged'

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "call_bridged",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "state": "bridged"
    }
}

Call Hangup Webhook

Field Value
call_control_id Unique call id used to issue commands via call control API
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
connection_id Telnyx connection id used in the call
end_time ISO-8601 datetime of when call was hangup
from Number or SIP URI placing the call
hangup_cause The reason the call was ended ('call_rejected', `no_answer`, 'normal_clearing', 'originator_cancel', 'timeout', 'time_limit', 'user_busy', 'not_found' or 'unspecified')
hangup_source The party who ended the call ('callee', 'caller', 'unknown')
occurred_at ISO-8601 datetime of when the event occurred
sip_hangup_cause The reason the call was ended (SIP response code). If the SIP response is unavailable (in inbound calls for example) this is set to 'unspecified'.
start_time ISO-8601 datetime of when call was received
to Destination number or SIP URI of the call

Hang-up Cause Detail

Hang-up Cause Description
call_rejected Callee chose not to accept this call. The callee is not busy nor incompatible.
normal_clearing Call is being cleared because one of the users involved in the call has requested that the call be cleared.
originator_cancel SIP request has been terminated by a bye or cancel.
timeout Call was canceled because the destination channel took too long to answer.
time_limit Call lasted the maximum allowable duration of 4 hours or a custom time limit configured in the Dial or Transfer call commands.
user_busy Called party is unable to accept another call because the user busy condition has been encountered.
not_found Called party cannot be reached because the valid destination number is not currently allocated (assigned).
unspecified Unexpected hangup not matching any of the above causes. `sip_hangup_cause` contained in the webhook may contain additional information.

Hang-up Source Detail

Hang-up Source Description
caller The call was hung up by the caller.
callee The call was hung up by the individual who was dialed.
unknown The source of the hang up could not be resolved.

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "call_hangup",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "call_control_id": "v2:AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpW",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "end_time": "2018-02-02T22:25:29.422345Z",
        "from": "+35319605860",
        "hangup_cause": "call_rejected",
        "hangup_source": "callee",
        "occurred_at": "2018-02-02T22:25:29.422345Z",
        "sip_hangup_cause": "603",
        "start_time": "2018-02-02T22:25:27.521992Z",
        "to": "+13129457420"    
    }
}

Call Initiated Webhook

A call initiated webhook informs a user of an incoming call. The webhook must be followed by either an answer command, a hangup command, or a reject command.

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
start_time ISO-8601 datetime of when call was received
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
direction Whether the call is 'incoming' or 'outgoing'
state Whether the call is in 'bridging' or 'parked' state

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "call_initiated",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "start_time": "2018-02-02T22:25:27.521992Z",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "direction": "incoming",
        "state": "parked"
    }
}

DTMF Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
digit The received DTMF digit or symbol

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "dtmf",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "digit": "#"
    }
}

Gather Ended Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
digits A string containing the full DTMF sequence gather on Gather command (doesn't contain the 'terminating_digit')
status Can be either "valid", "invalid", or "call_hangup"

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "gather_ended",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "digits": "5503",
        "status": "valid"
    }
}

Playback Started Webhook

Field Value
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
media_url The audio URL being played back
overlay Whether the audio is going to be played in overlay mode or not

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "playback_started",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "media_url": "http://example.com/audio.wav",
        "overlay": false
    }
}

Playback Ended Webhook

Field Value
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
media_url The audio URL played back
overlay Whether the audio was played in overlay mode or not
status Can be either "completed" or "call_hangup"

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "playback_ended",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "media_url": "http://example.com/audio.wav",
        "overlay": false,
        "status": "completed"
    }
}

Recording Saved Webhook

Field Value
occurred_at ISO-8601 datetime of when the event occurred
recording_started_at ISO-8601 datetime of when recording commenced
recording_ended_at ISO-8601 datetime of when the recording completed
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
connection_id Telnyx connection id used in the call
channels Whether the recording was recorded in 'single' or 'dual' channel
recording_urls A json object containing the recording URL (ex.: {FORMAT: URL}, where format can be 'mp3' or 'wav'). The URL is valid for 10 minutes. After 10 minutes, you may retrieve recordings via API using Reports -> Call Recordings documentation, or via Mission Control under Reporting -> Recordings
public_recording_urls A json object containing the recording URL (ex.: {FORMAT: URL}, where format can be 'mp3' or 'wav'). The URL is valid for as long as the file exists. For security purposes, this feature is activated on a per request basis. Please contact customer support with your Account ID to request activation.

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "recording_saved",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "recording_started_at": "2018-02-02T22:25:27.521992Z",
        "recording_ended_at": "2018-02-02T22:25:27.521992Z",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "channels": "single",
        "recording_urls": {"mp3": "http://RECORDING_URL"},
        "public_recording_urls": {"mp3": "http://RECORDING_URL"},
    }
}

Speak Started Webhook

Field Value
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "speak_started",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "occured_at": "2018-02-02T22:25:27.521992Z",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d"
    }
}

Speak Ended Webhook

Field Value
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
status Can be either "completed" or "call_hangup"

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "speak_ended",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "occured_at": "2018-02-02T22:25:27.521992Z",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "status": "completed"
    }
}

Answering Machine Detection Result Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
result Can be one of "human", "machine" or "not_sure"

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "amd_result",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "result": "machine"
    }
}

Answering Machine Greeting Ended Webhook

Field Value
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
occurred_at ISO-8601 datetime of when the event occurred
call_control_id call id used to issue commands via call control API
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events
client_state State received from a command
result Can be one of "ended" or "not_sure"

Example

{
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "amd_greeting_ended",
    "created_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
        "to": "+13129457420",
        "occurred_at": "2018-02-02T22:25:27.521992Z",
        "from": "+35319605860",
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "connection_id": "7267xxxxxxxxxxxxxx",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
        "result": "ended"
    }
}

Fork Start Webhook

Field Value
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events

Example

{
    "record_type": "event",
    "id": "fc9fc3d0-b008-442f-b34e-b63f606f3153",
    "event_type": "fork_start",
    "created_at": "2019-06-19T19:17:27.067394888Z",
    "payload": {
      "connection_id": "1132xxxxxxxxxxxxxxx",
      "call_leg_id": "ded50426-92c6-11e9-b4b0-02420a0f6e68",
      "call_session_id": "ded50ffc-92c6-11e9-bb08-02420a0f6e68"
    }
}

Fork Stop Webhook

Field Value
connection_id Telnyx connection id used in the call
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID that is unique to the call session and can be used to correlate webhook events

Example

{
    "record_type": "event",
    "id": "068f504f-cf55-4836-a0d0-949f3aaa3b3e",
    "event_type": "fork_stop",
    "created_at": "2019-06-19T19:17:33.821584056Z",
    "payload": {
        "connection_id": "1132xxxxxxxxxxxxxxx",
        "call_leg_id": "ded50426-92c6-11e9-b4b0-02420a0f6e68",
        "call_session_id": "ded50ffc-92c6-11e9-bb08-02420a0f6e68"
    }
}
Was this page helpful?