Conversations API

Use GET /api/v1/rest/conversations/live for the live web inbox. User-scoped tokens can take over, hand back, assign, mark read and reply through POST /api/v1/rest/conversations/:id/advisor; departed visitors and voice sessions cannot be claimed as live text chats. The annotations endpoint reads and changes tags, labels, notes and summary ratings. Each action has a matching named MCP tool; see the reference for schemas and permissions.

Every conversation an agent has — web, phone, SMS, email, or campaign outbound — is recorded and readable here. Reading is gated on conversations.read; deleting on conversations.write.

List conversations

GET /api/v1/rest/conversations   ?widget_id= &simulated= &limit= &offset=

Newest first, in a { data, total, limit, offset } envelope (limit max 100, default 50). Test runs are excluded by default — pass simulated=1 for only simulations or simulated=all for both. Each row:

{
  "id":               "uuid",
  "widget_id":        "uuid",
  "surface":          "web",
  "is_simulated":     false,
  "started_at":       "2026-07-01T14:12:00Z",
  "duration_seconds": 184,
  "page_url":         "https://example.com/pricing",
  "intent":           "service booking",
  "outcome":          "completed",
  "extracted_data":   { "name": "Sam", "phone": "+14165550100" },
  "criteria_results": [ { "criterion": "…", "verdict": "pass" } ]
}

Get one conversation

GET /api/v1/rest/conversations/:id

Adds the full transcript (ordered messages), the tool_calls the agent made ({ name, args, ts }), and a card_url you can iframe for an inline preview.

Delete a conversation

DELETE /api/v1/rest/conversations/:id

Removes the conversation and its events. The usage record is preserved but anonymized (its conversation reference is cleared). This cannot be undone.

Reacting to conversations

To react in real time, subscribe to the conversation.started, conversation.ended, and conversation.evaluated events with the Webhooks API instead of polling. Goal verdicts land in criteria_resultsonce evaluation completes (criteria that don't apply are marked not_applicableand don't count against the pass rate). Full schemas are in the OpenAPI reference.