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. Both deliver the same event objects.
Event types
Section titled “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
Section titled “Event objects”{ "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!" } }}datais a snapshot of the resource when the event occurred. It does not change if the resource is later edited.originis the channel the change came from:web(the Messenger),dashboard,api,email, orsystem.actoris the participant or API key that caused the change, ornull. When an assistant replies, adds a note, escalates, or updates the user in response to a message,actoris the participant who sent that message. The assistant is identified indata, such asmessage.senderorescalation.assistantId.causationIdlinks events to the API request that caused them, when available. Events caused by one request share it.
Polling for new events
Section titled “Polling for new events”Poll in ascending order and keep the latest cursor:
curl "https://optlo.com/api/v1/events?order=asc&cursor=SAVED_CURSOR" \ -H "Authorization: Bearer YOUR_API_KEY"- Start without a cursor to read from the oldest retained event.
- Process each event in
data, then savenextCursor. - Request the next page with the saved cursor. When you are caught up,
datais empty; keep polling with the returnednextCursor.
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
Section titled “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:
- Re-read the resources you mirror, such as users and conversations, from their list endpoints. See Pagination.
- Start polling again without a cursor, and process events idempotently, since some will overlap the resources you just read.