> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/conversations-api/api-reference/events.md).

# Events

## Conversations API: Webhook Event Types

The Conversations API enables you to monitor conversation changes in real-time using webhooks. Three key event types are supported:

### Event Types

1. **conversation.created**
   * **Use Case:** Monitor the initiation of new customer interactions.
   * **Triggered:** When a new conversation is created.
2. **conversation.updated**
   * **Use Case:** Track changes in active conversations, such as updated statuses or participant modifications.
   * **Triggered:** When an existing conversation is updated, with changes in attributes, participants, or statuses.
3. **conversation.deleted**
   * **Use Case:** Maintain clean data or trigger processes when conversations are archived or removed.
   * **Triggered:** When a conversation is deleted.

These events allow you to track the lifecycle of conversations efficiently.

### Webhook Payload Example

**conversation.updated Event Payload**

```json
{
  "service": "conversations",
  "event": "conversation.updated",
  "payload": {
    "id": "badbf15c-bad3-4bf3-9223-6b7f414f9770",
    "name": "",
    "description": "",
    "status": "active",
    "visibility": "private",
    "accessibility": "invite-only",
    "featuredParticipants": [
      {
        "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
        "type": "contact",
        "status": "active",
        "displayName": "Jane Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "facebookid-509207435603226",
          "identifierValue": "27612960145016998",
          "platformAddress": "27612960145016998"
        }
      },
      {
        "id": "5795352d-f111-407b-be33-c9db94e4a666",
        "type": "user",
        "status": "active",
        "displayName": "John Smith",
        "avatarUrl": ""
      }
    ],
    "activeParticipantCount": 2,
    "pendingParticipantCount": 0,
    "initiatingParticipant": {
      "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
      "type": "contact",
      "status": "active",
      "displayName": "Jane Doe",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "facebookid-509207435603226",
        "identifierValue": "27612960145016998",
        "platformAddress": "27612960145016998"
      }
    },
    "channelId": "8963269e-69e4-58aa-9bf0-9b6cc239329c",
    "lastMessage": {
      "id": "1ffdfcf0-5e4f-426b-adbc-c698b4bfc949",
      "type": "text",
      "preview": {
        "text": "hallo"
      },
      "recipients": null,
      "status": "delivered",
      "sender": {
        "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
        "type": "contact",
        "status": "active",
        "displayName": "Jane Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "facebookid-509207435603226",
          "identifierValue": "27612960145016998",
          "platformAddress": "27612960145016998"
        }
      },
      "createdAt": "2024-11-27T19:33:53.504Z"
    },
    "createdAt": "2024-11-26T18:45:28.809Z",
    "updatedAt": "2024-11-27T19:33:53.515Z",
    "platformStyle": "direct"
  }
}
```

### Webhook Configuration

### Webhook Configuration for Conversation Events

To subscribe to conversation events, you need to configure a webhook with the following parameters:

| Property      | Description                                                                                                          | Example Value                 |
| ------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Event Filters | Optional filters to narrow the scope of events, such as by `channelId`.                                              | `channelId:12345`             |
| Signing Key   | Key used for verifying the authenticity of incoming webhook requests.                                                | `abc123xyz456`                |
| URL           | The endpoint to which event notifications will be sent.                                                              | `https://example.com/webhook` |
| Event         | The specific event to track, options include `conversation.created`, `conversation.updated`, `conversation.deleted`. | `conversation.created`        |
| Service       | The service to monitor.                                                                                              |                               |

#### Webhook Configuration Example

```json
{
  "service": "conversations",
  "event": "conversation.created",
  "url": "http://site",
  "signingKey": "key",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "<id>"
    }
  ]
}

```

<br>