# Events

Events record changes in a workspace, such as a new conversation, message, or note. Read them by polling `GET /api/v1/events`, or receive them as they happen with [webhooks](/docs/api-reference/webhooks/). Both deliver the same event objects.

## Event types

| Type                     | Read scope           | Occurs when                                  |
| ------------------------ | -------------------- | -------------------------------------------- |
| `user.email_captured`    | `users:read`         | A user's email address is captured           |
| `conversation.created`   | `conversations:read` | A conversation starts                        |
| `conversation.closed`    | `conversations:read` | A conversation is closed                     |
| `conversation.reopened`  | `conversations:read` | A closed conversation is reopened            |
| `conversation.escalated` | `conversations:read` | A conversation is escalated to the team      |
| `message.created`        | `messages:read`      | A customer-visible message is sent by anyone |
| `note.created`           | `notes:read`         | An internal note is added                    |

A key sees only the event types its read scopes allow. Filtering by a type the key cannot read returns `403 permission_denied`. New event types may be added; ignore types you do not handle.

## Event objects

```json
{
  "id": "evnt_…",
  "version": 1,
  "type": "message.created",
  "workspaceId": "ws_…",
  "createdAt": "2026-10-31T09:14:03.120Z",
  "origin": "email",
  "actor": { "role": "user", "id": "user_…" },
  "causationId": null,
  "data": {
    "message": { "id": "msg_…", "conversationId": "conv_…", "content": "Thanks!" }
  }
}
```

- `data` is a snapshot of the resource when the event occurred. It does not change if the resource is later edited.
- `origin` is the channel the change came from: `web` (the Messenger), `dashboard`, `api`, `email`, or `system`.
- `actor` is the participant or API key that caused the change, or `null`. When an assistant replies, adds a note, escalates, or updates the user in response to a message, `actor` is the participant who sent that message. The assistant is identified in `data`, such as `message.sender` or `escalation.assistantId`.
- `causationId` links events to the API request that caused them, when available. Events caused by one request share it.

## Polling for new events

Poll in ascending order and keep the latest cursor:

```sh
curl "https://optlo.com/api/v1/events?order=asc&cursor=SAVED_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

1. Start without a cursor to read from the oldest retained event.
2. Process each event in `data`, then save `nextCursor`.
3. Request the next page with the saved cursor. When you are caught up, `data` is empty; keep polling with the returned `nextCursor`.

In ascending order, `nextCursor` is always present, including on empty pages. Always save the newest value — it moves forward even when a page contains no events your key can see.

Process events idempotently using `id`. A crash between processing and saving the cursor causes the same events to be read again.

The default order is descending, newest first, which suits browsing recent activity. Use `type` to read a single event type. A cursor is bound to its order, type filter, and the key's read scopes; changing any of them requires starting again without a cursor. Cursors survive API key rotation when the new key has the same scopes.

## Retention and expired cursors

Events are retained for 30 days after they are ingested. A cursor that points to events which have expired returns `410 event_cursor_expired`.

A poller that keeps up is unaffected: each request with a caught-up cursor renews it for another 30 days. A cursor expires only if your integration stops polling, or falls behind, for longer than the retention period.

When you receive `410`, events have been missed and cannot be replayed. Resynchronize instead:

1. Re-read the resources you mirror, such as users and conversations, from their list endpoints. See [Pagination](/docs/api-reference/pagination/).
2. Start polling again without a cursor, and process events idempotently, since some will overlap the resources you just read.
