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


---

# 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/conversations-api/api-reference/events.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.