# 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](https://docs.messagebird.com/api/notifications-api/api-reference/webhooks/create-a-webhook-subscription))

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

```json
{
  "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

<table><thead><tr><th width="259">Property</th><th>Description</th><th>Example value</th></tr></thead><tbody><tr><td>service</td><td>The Bird CRM service which generates the event</td><td>channels</td></tr><tr><td>event</td><td>The specific event you are subscribing too. </td><td>voice..inbound</td></tr><tr><td>url</td><td>The webhook endpoint</td><td>https://site</td></tr><tr><td>signingKey</td><td>A value that will be used to validate a webhook</td><td>key</td></tr><tr><td>eventFilters[]</td><td>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).</td><td>"key": "channelId", "value": "" }, { "key": "status", "value": "delivered"}</td></tr></tbody></table>

### 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**

```json
{
  "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

<table><thead><tr><th width="259">Property</th><th>Description</th><th>Example value</th></tr></thead><tbody><tr><td>service</td><td>The Bird CRM service which generates the event</td><td>channels</td></tr><tr><td>event</td><td>The specific event you are subscribing too. </td><td>voice.outbound</td></tr><tr><td>url</td><td>The webhook endpoint</td><td>https://site</td></tr><tr><td>signingKey</td><td>A value that will be used to validate a webhook</td><td>key</td></tr><tr><td>eventFilters[]</td><td>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).</td><td>"key": "channelId", "value": "" }, { "key": "status", "value": "delivered"}</td></tr></tbody></table>