Messaging & channels
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. Default 50, maximum 500. |
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 SMS with
PATCH /assistants/{id}/sms-enabledor WhatsApp text withPATCH /assistants/{id}/whatsapp-enabled. - Calls: the equivalent view for voice.