Skip to content

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.

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.

{
"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.

Poll in ascending order and keep the latest cursor:

Terminal window
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.

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.
  2. Start polling again without a cursor, and process events idempotently, since some will overlap the resources you just read.