Guides
Conversations
Read messaging activity across web chat, SMS, and WhatsApp — filtered lists, statuses, summaries, and export.
Conversations are the messaging counterpart to calls: every web-chat, SMS, or WhatsApp exchange an assistant handles becomes a conversation record. Like calls, this surface is read-only — conversations are created by inbound traffic on your channels, and these endpoints let you list, inspect, and export them.
| Method | Path | Purpose |
|---|---|---|
| GET | /conversations | List conversations with filters and pagination |
| GET | /conversations/statuses | Distinct conversation statuses in your tenant |
| GET | /conversations/summary-by-assistant | Per-assistant conversation counts |
| GET | /conversations/export | Bulk export (up to 10,000 rows) |
| GET | /conversations/{id} | One conversation with full detail |
List conversations#
GET /conversations
| Query param | Type | Required | Description |
|---|---|---|---|
limit | number | No | Page size, max 500 (default 50) |
offset | number | No | Items to skip (default 0) |
assistantId | UUID | No | Only conversations handled by this assistant |
channel | web | sms | whatsapp | No | Filter by messaging channel |
status | string | No | Filter by status (values from /conversations/statuses) |
dateFrom / dateTo | ISO 8601 datetime (with offset) | No | Time window |
sortBy | startedAt | createdAt | No | Sort key (default startedAt) |
search | string | No | Free-text search |
curl "https://core-api.heysadie.ai/conversations?channel=sms&limit=100" \
-H "Authorization: ApiKey YOUR_API_KEY"Conversation fields#
| Field | Description |
|---|---|
id, conversationId | Record and conversation identifiers |
assistantId, assistantName | Which assistant handled it |
channel | web, sms, or whatsapp |
customerIdentifier | Who the customer is on that channel (e.g. their number) |
status, endedReason | Lifecycle state and how it ended |
startedAt, closedAt | Timing |
lastInboundAt, lastOutboundAt | Last message in each direction |
transcript, messages | The message history |
summary, analysis | AI-generated summary and structured analysis |
cost, costBreakdown | Billing detail — returned by the detail route only |
Discover statuses#
GET /conversations/statuses returns the distinct status strings occurring in your tenant, for building filters.
curl https://core-api.heysadie.ai/conversations/statuses \
-H "Authorization: ApiKey YOUR_API_KEY"Per-assistant summaries#
GET /conversations/summary-by-assistant returns one row per assistant with assistantId, assistantName, and count (the number of conversations).
curl https://core-api.heysadie.ai/conversations/summary-by-assistant \
-H "Authorization: ApiKey YOUR_API_KEY"Export conversations in bulk#
GET /conversations/export returns up to 10,000 conversations as JSON. It accepts the list filters (assistantId, channel, status, dateFrom, dateTo, search) but no pagination — narrow with date ranges on busy tenants.
curl "https://core-api.heysadie.ai/conversations/export?channel=whatsapp&dateFrom=2026-07-01T00:00:00%2B00:00" \
-H "Authorization: ApiKey YOUR_API_KEY"Get one conversation#
GET /conversations/{id} returns the full record, including cost and costBreakdown, which the list routes omit.
curl https://core-api.heysadie.ai/conversations/CONVERSATION_ID \
-H "Authorization: ApiKey YOUR_API_KEY"Next steps#
- Assistants — enable the SMS channel with
PATCH /assistants/{id}/sms-enabled. - Calls — the equivalent view for voice.