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
service	The Bird CRM service which generates the event	channels
event	The specific event you are subscribing too.	voice..inbound
url	The webhook endpoint	https://site
signingKey	A value that will be used to validate a webhook	key
eventFilters[]	Event filters are inclusive, which means you will only get events for filters you add. If you do not add a filter you will get all events (except where you have other webhooks with an explicit filter).	"key": "channelId", "value": "" }, { "key": "status", "value": "delivered"}

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
service	The Bird CRM service which generates the event	channels
event	The specific event you are subscribing too.	voice.outbound
url	The webhook endpoint	https://site
signingKey	A value that will be used to validate a webhook	key
eventFilters[]	Event filters are inclusive, which means you will only get events for filters you add. If you do not add a filter you will get all events (except where you have other webhooks with an explicit filter).	"key": "channelId", "value": "" }, { "key": "status", "value": "delivered"}