SMAO API Documentation
Public APIWebsite chats

List website chats (paginated)

GET
/chats

Chats from the website widget, newest activity first (last_message_at descending). Chats in which the visitor never wrote are not listed.

The order follows activity, so a chat that receives a message while you page moves back to the front: it shows up on your next sync, not in the current pass. For incremental sync, keep the newest last_message_at you have seen and pass it as last_message_from next time.

Authorization

bearerAuth
AuthorizationBearer <token>

API key in the Authorization: Bearer <key> header. Keys are created in the SMAO dashboard (Settings → API Keys).

In: header

Query Parameters

cursor?string

Opaque cursor from a prior meta.next_cursor. Base64url-encoded (unpadded) - do not parse or construct it manually.

Match^[A-Za-z0-9_-]+$
limit?integer

Items per page (1–100, default 25).

Range1 <= value <= 100
Default25
status?string

Only open or only closed chats. Omit for both.

Value in

  • "open"
  • "closed"
widget_id?string

Filter by widget.

Match^[a-f0-9]{24}$
needs_human?boolean

true - the chat waits for a reply from the team: the visitor was handed over or wrote in a chat the team answers, and no team member has replied or taken over since.

last_message_from?string

Only chats whose last message is at or after this time.

Formatdate-time
last_message_to?string

Only chats whose last message is at or before this time.

Formatdate-time

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/chats"
{  "data": [    {      "id": "string",      "widget_id": "string",      "widget_name": "string",      "assistant_id": "string",      "assistant_name": "string",      "language": "string",      "status": "open",      "current_responder": "ai",      "needs_human": true,      "human_request_reason": "explicit_request",      "human_requested_at": "2019-08-24T14:15:22Z",      "human_takeover_at": "2019-08-24T14:15:22Z",      "visitor": {        "name": "string",        "email": "user@example.com"      },      "page_url": "string",      "origin": "string",      "last_message_preview": "string",      "last_message_author": "visitor",      "last_message_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "closed_at": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "has_more": true,    "next_cursor": "string"  }}

Permanently delete the call recording DELETE

**Irreversible.** Erases every audio artifact of the call from object storage - the master recording, both channel recordings, the playback transcode and the waveform data - and reports success only after the deletion has been verified. The call itself is kept: transcript, analyses, notes, metadata and diagnostics are untouched, and the call keeps appearing in `GET /calls`.

Get a website chat with its messages GET

The chat and the messages the visitor saw, oldest first: visitor messages, AI replies, team replies, and system notices. Internal messages such as the AI's tool calls are not included. Reading a chat never marks it as read.