Conversations API

Query the full conversation history for your widgets — transcripts, tool calls, extracted data, outcomes. Use it to sync transcripts into your CRM, build custom analytics, or train internal models on real visitor interactions.

The conversation object

{
  "id":              "conv_xyz789",
  "widget_id":       "wgt_abc123",
  "started_at":      "2026-04-10T12:34:00Z",
  "ended_at":        "2026-04-10T12:36:07Z",
  "duration_seconds": 127,
  "credits_charged":  127,
  "page_url":        "https://northwindcatering.example/catering",
  "outcome":         "completed",
  "visitor": {
    "ip_country":  "US",
    "ip_region":   "CA",
    "user_agent":  "Mozilla/5.0..."
  },
  "transcript": [
    { "role": "agent", "text": "Hi! I'm Sam...", "ts": "2026-04-10T12:34:01Z" },
    { "role": "user",  "text": "Do you cater vegan?", "ts": "2026-04-10T12:34:08Z" }
  ],
  "tool_calls": [
    {
      "name":    "search_site",
      "args":    { "query": "vegan catering" },
      "result":  "Yes — our grilled veggie platter is fully vegan...",
      "ts":      "2026-04-10T12:34:10Z"
    }
  ],
  "extracted_data": {
    "intent":      "catering_inquiry",
    "event_date":  "2026-06-15",
    "guest_count": 50
  },
  "criteria_results": {
    "answered_visitor_question":   { "passed": true,  "reasoning": "..." },
    "collected_contact_info":      { "passed": false, "reasoning": "..." }
  }
}

List conversations

GET /api/v1/conversations?widget_id=wgt_abc123&limit=50&since=2026-04-01

Query parameters:

• widget_id — filter to one widget (optional)
• since — ISO timestamp, inclusive
• until — ISO timestamp, exclusive
• outcome — completed, abandoned, error
• limit — max 200, default 50
• cursor — pagination cursor from previous response

Get one conversation

GET /api/v1/conversations/:id

Export transcripts

GET /api/v1/conversations/:id/transcript?format=txt

Returns the transcript as plain text (txt), markdown (md), or speaker-labeled JSON (json). Useful for piping into human-readable reports.

Extracted data + acceptance criteria

If you've defined an extraction schema or acceptance criteria on the widget's Goals tab, every completed conversation includes:

• extracted_data— the filled-in schema fields (name, email, event date, etc.)
• criteria_results— pass/fail plus the model's reasoning for each acceptance criterion

Extraction happens asynchronously right after the call ends. If you fetch a conversation within a second or two of ended_at, the fields may still be populating.

Deleting a conversation

DELETE /api/v1/conversations/:id

Permanently deletes the transcript, tool calls, and extracted data. The usage record (for billing) is preserved but anonymized — the conversation_id is set to null.

Real-time updates

For live data, subscribe to the conversation.ended and criteria.evaluated webhooks instead of polling. See Webhooks.