Receiving Webhooks for Programmable Voice

When you send a Voice API command and receive a successful response (i.e. 200 OK), you can expect to receive a webhook. The webhook will be delivered to the primary URL specified on the Voice API Application associated with the call. If that URL does not resolve, or your application returns a non 200 OK response, the webhook will be delivered to the failover URL, if one has been specified.

In order to minimize webhook delivery time, Telnyx:

• does not enforce the order in which webhooks are delivered
• retries webhook delivery if your application does not respond within a certain time threshold.

As a result, you may encounter:

• out-of-order webhooks
• simultaneous (or near simultaneous) webhooks
• duplicate webhooks

Duplicate webhooks may cause your application to issue duplicate commands. You can instruct Telnyx to ignore duplicate commands by sending a command_id parameter as part of your commands. Commands with duplicate command_ids within 60 seconds will be ignored.

Webhooks contain a variety of ID fields which describe them and correlate them with calls.

When you place an incoming call to a number associated with your Voice API Application, you will receive a callback for the incoming call. It should look something like the JSON below:

{
  "data": {
    "record_type": "event",
    "event_type": "call.initiated",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "call_leg_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "from": "+1-202-555-0133",
      "to": "+12025550131",
      "direction": "incoming",
      "state": "parked"
    }
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://example.com/webhooks"
  }
}

Note

After pasting the above content, Kindly check and remove any new line added

Field	Value
record_type	Description of the record.
event_type	The type of event detected by the Telnyx system
id	unique id for the webhook
occurred_at	ISO-8601 datetime of when event occured
call_control_id	call id used to issue commands via Voice API
connection_id	Voice API App ID (formerly 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. Call session is a group of related call legs that logically belong to the same phone call, e.g. an inbound and outbound leg of a transferred call.
client_state	State received from a command
from	Number or SIP URI placing the call
to	Destination number or SIP URI of the call
direction	Whether the call is 'incoming' or 'outgoing'
state	Whether the call is in 'bridging' or 'parked' state