# Events

> Subscribe to lifecycle, connection, conversation, and message events with on().

Source: https://docs.useclad.ai/events

---

Subscribe with `on()`, which returns an **unsubscribe** function. Every event
uses the same envelope.

```ts
const off = chat.on("message:received", (event) => {
  console.log(event.payload.conversation.id, event.payload.message.id);
});

off(); // stop listening
```

```ts
interface ChatEvent<TPayload> {
  id: string;
  type: ChatEventName;
  createdAt: string;   // ISO‑8601
  payload: TPayload;
}
```

### Event reference

| Event | Payload (key fields) | Fires when |
|---|---|---|
| `ready` | `{ identityType }` | The widget has booted and is ready. |
| `error` | `{ code, message }` | A recoverable/visible error occurred. |
| `open` / `close` | — | The messenger panel opened/closed. |
| `show` / `hide` | — | All surfaces shown/hidden. |
| `launcher:show` / `launcher:hide` | — | The launcher visibility changed. |
| `auth:expired` | — | The identity token expired (refresh underway). |
| `auth:changed` | `{ identityType }` | The user became identified. |
| `connection:state` | `{ state }` | `connecting` / `connected` / `reconnecting` / `disconnected`. |
| `unread:change` | `{ count }` | The total unread count changed. |
| `conversation:started` | `{ conversation }` | A conversation was created. |
| `conversation:opened` | `{ conversation }` | A conversation was opened in the UI. |
| `conversation:updated` | `{ conversation }` | Status/assignee/etc. changed. |
| `conversation:resolved` | `{ conversation }` | A conversation was resolved/closed. |
| `conversation:assigned` | `{ conversation }` | An agent/team was assigned. |
| `message:sending` | `{ conversation, message }` | An outbound message is being sent. |
| `message:sent` | `{ conversation, message }` | An outbound message was accepted. |
| `message:received` | `{ conversation, message }` | An agent/bot message arrived. |
| `message:failed` | `{ conversation, error }` | A message failed to send. |
| `message:read` | `{ conversation }` | A message was read. |
| `typing:start` / `typing:stop` | `{ conversationId }` | Typing indicator changed. |
| `article:opened` | `{ articleId }` | A KB article was opened. |
| `form:opened` | `{ formId }` | A ticket form was opened. |
| `form:submitted` | `{ formId, conversationId }` | A ticket form was submitted. |