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

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

Last updated