Voice webhooks

Voice calls go through a life-cycle during the call; life-cycle events provide an indication of the current status a voice call has; started or starting are both examples of voice call statuses.

Voice Lifecycle events

You can create a webhook subscription to listen to voice lifecycle events (see API details here)

Voice supports two lifecycle event webhook types

• voice.inbound

• voice.outbound

voice.inbound

This event is used to get notified about incoming voice calls

Filter by call status

By default, when creating a subscription without specifying any call status filter, you are going to receive events for all applicable call status events that occur during the call.

The inbound call status can be:

• starting

  • The call has been initiated

• ringing

  • The destination number has started ringing

• ongoing

  • The call is in progress

• completed

  • The call has been successfully completed

• no-answer

  • The call was not answered

• busy

  • The destination number is busy

• failed

  • The call has failed

It is possible to add filters to only receive events for a specific call status. You can add multiple status filters to only get those specified events.

Filter channel ID

By default, when creating a subscription without specifying a channel ID filter, you are going to receive events for all incoming calls for all voice channels.

It is possible to add filters to only receive events for a specific channel ID.

For each subscription, it is only possible to add one channelId filter.

Example event

{
  "service": "channels",
  "event": "voice.inbound",
  "url": "https://yoururl.com",
  "signingKey": "mysecretkey",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "b827924e-9789-4c2f-a4d5-b352175354f6"
    },
    {
      "key": "status",
      "value": "completed"
    },
    {
      "key": "status",
      "value": "starting"
    }
  ]
}

Event properties

Property	Description	Example value

voice.outbound

This event is used to get notified about the status of outgoing voice calls

Filter by call status

By default, when creating a subscription without specifying any call status filter, you are going to receive events for all applicable call status events that occur during the call.

The outbound call status can be:

• accepted

  • When an outgoing call has been accepted by the Voice API

• starting

  • The call has been initiated

• ringing

  • The destination number has started ringing

• ongoing

  • The call is in progress

• completed

  • The call has been successfully completed

• no-answer

  • The call was not answered

• busy

  • The destination number is busy

• failed

  • The outgoing call has failed

• cancelled

  • The outgoing call has been cancelled

It is possible to add filters to only receive events for a specific call status. You can add multiple status filters to only get those specified events.

Filter channel ID

By default, when creating a subscription without specifying a channel ID filter, you are going to receive events for all outgoing calls for all voice channels.

It is possible to add filters to only receive events for a specific channel ID.

For each subscription, it is only possible to add one channelId filter.

Example event

{
  "service": "channels",
  "event": "voice.outbound",
  "url": "https://yoururl.com",
  "signingKey": "mysecretkey",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "b827924e-9789-4c2f-a4d5-b352175354f6"
    },
    {
      "key": "status",
      "value": "completed"
    }
  ]
}

Event properties

Property	Description	Example value