# Chesly API events

> Every event type the Chesly API sends through webhooks, the live stream and the feed, with its data. Start a trial and make keys at https://web.chesly.app/api. Agent setup: https://agents.chesly.app/agents.md

## The envelope

Every event comes the same way, through a [webhook](https://agents.chesly.app/docs/webhooks), the live stream at `GET /v1/events/stream` or the feed at `GET /v1/events`: an object whose `data` depends on its `type`.

| Field | Type | Description |
|---|---|---|
| `id` | string | The event's ID (evt_…): dedupe by it. |
| `type` | string | The event's type: one of those below. |
| `timestamp` | time (ISO 8601) |  |
| `data` | object | The type's data, as each section below shows it. |

Events are kept for 7 days on Personal and 30 on Pro, and one can arrive twice: skip an `id` you've seen. A webhook whose `payload` is `ids` gets only the IDs below in `data`, and reads the rest from the API. Email events come only when you ask for them, with `networks` including `email`.

## `message.received`

Someone sends you a message, on any network you connected.

| Field of `data` | Type | Description |
|---|---|---|
| `message` | [Message](https://agents.chesly.app/docs/api#message) |  |
| `chat` | object |  |
| `chat.id` | string | The chat's ID (chat_…). |
| `chat.name` | string or null |  |
| `chat.network` | string |  |
| `chat.type` | `dm` or `group` |  |

With payload `ids`, `data` holds `message_id`, `chat_id` and `account_id`.

## `message.sent`

You send a message, from any device or through the API.

| Field of `data` | Type | Description |
|---|---|---|
| `message` | [Message](https://agents.chesly.app/docs/api#message) |  |
| `chat` | object |  |
| `chat.id` | string | The chat's ID (chat_…). |
| `chat.name` | string or null |  |
| `chat.network` | string |  |
| `chat.type` | `dm` or `group` |  |

With payload `ids`, `data` holds `message_id`, `chat_id` and `account_id`.

## `message.edited`

A message is edited. Its `message` carries the text after the edit.

| Field of `data` | Type | Description |
|---|---|---|
| `message` | [Message](https://agents.chesly.app/docs/api#message) |  |
| `chat` | object |  |
| `chat.id` | string | The chat's ID (chat_…). |
| `chat.name` | string or null |  |
| `chat.network` | string |  |
| `chat.type` | `dm` or `group` |  |

With payload `ids`, `data` holds `message_id`, `chat_id` and `account_id`.

## `message.deleted`

A message is deleted.

| Field of `data` | Type | Description |
|---|---|---|
| `message_id` | string | The message's ID (msg_…). |
| `chat_id` | string | The chat's ID (chat_…). |

With payload `ids`, `data` is the same.

## `message.delivery_failed`

A message you sent through the API didn't go through. With `error.certain: false` (a `timeout`, or an `unknown` error), it may have gone out anyway: check the chat before you send it again. If such a failure turns out certain, a second `message.delivery_failed` for the same message follows, with `certain: true`.

| Field of `data` | Type | Description |
|---|---|---|
| `message_id` | string | The message's ID (msg_…). |
| `chat_id` | string | The chat's ID (chat_…). |
| `error` | [DeliveryError](https://agents.chesly.app/docs/api#deliveryerror) or null |  |

With payload `ids`, `data` holds `message_id` and `chat_id`.

## `chat.created`

A chat starts.

| Field of `data` | Type | Description |
|---|---|---|
| `chat` | [Chat](https://agents.chesly.app/docs/api#chat) |  |

With payload `ids`, `data` holds `chat_id`.

## `chat.updated`

A chat changes: `changes` names what did, and `chat` is the chat as it is now, or null once you've left it.

| Field of `data` | Type | Description |
|---|---|---|
| `chat_id` | string |  |
| `chat` | [Chat](https://agents.chesly.app/docs/api#chat) or null | The chat as it is now; null once the user has left it. |
| `changes` | array of `name`, `archived`, `pinned`, `muted` or `left` |  |

With payload `ids`, `data` holds `chat_id`.

## `chat.read`

A chat is read, on any device or through the API.

| Field of `data` | Type | Description |
|---|---|---|
| `chat_id` | string |  |
| `last_read_message_id` | string or null |  |

With payload `ids`, `data` holds `chat_id`.

## `account.connected`

You connect an account in the Chesly app.

| Field of `data` | Type | Description |
|---|---|---|
| `account` | [Account](https://agents.chesly.app/docs/api#account) |  |

With payload `ids`, `data` holds `account_id`.

## `account.disconnected`

An account is disconnected.

| Field of `data` | Type | Description |
|---|---|---|
| `account` | [Account](https://agents.chesly.app/docs/api#account) |  |

With payload `ids`, `data` holds `account_id`.

## `account.needs_attention`

An account needs you: reconnect it in the Chesly app.

| Field of `data` | Type | Description |
|---|---|---|
| `account` | [Account](https://agents.chesly.app/docs/api#account) |  |

With payload `ids`, `data` holds `account_id`.

## `reaction.added`

Someone reacts to a message.

| Field of `data` | Type | Description |
|---|---|---|
| `message_id` | string | The message's ID (msg_…). |
| `chat_id` | string | The chat's ID (chat_…). |
| `reaction` | object |  |
| `reaction.key` | string | The reaction, usually an emoji. |
| `reaction.sender` | object |  |
| `reaction.sender.name` | string |  |
| `reaction.sender.is_me` | boolean |  |

With payload `ids`, `data` holds `message_id` and `chat_id`.

## `reaction.removed`

Someone takes a reaction back.

| Field of `data` | Type | Description |
|---|---|---|
| `message_id` | string | The message's ID (msg_…). |
| `chat_id` | string | The chat's ID (chat_…). |
| `reaction` | object |  |
| `reaction.key` | string | The reaction, usually an emoji. |
| `reaction.sender` | object |  |
| `reaction.sender.name` | string |  |
| `reaction.sender.is_me` | boolean |  |

With payload `ids`, `data` holds `message_id` and `chat_id`.