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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/voice-api/voice-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.