Skip to main content
POST
Appends the visitor message to the thread (creating one when threadId is missing or unknown, restoring it from threadMessages when supplied) and answers with the assistant reply. With stream: true the response is text/event-stream; otherwise JSON. A freshly created thread discloses its capability token once (threadToken in JSON or the leading SSE thread event). Attachments are validated first (max 5, 10 MB each, image/PDF/text/CSV; 400 invalid_attachment / 413 payload_too_large). A post with neither message text nor attachments answers 400 { error: 'message required' } (as POST /api/threads/{id}/messages does) before any thread is created, restored or given a token. An existing thread keeps its stored provider; a body provider only selects the provider for this reply. Native human takeover may return a JSON liveChat acknowledgement even with stream=true. With clientMessageId and session identity, complete replies replay for ten minutes with X-Idempotent-Replay: true. 409 message_outcome_unknown requires conversation refresh and reconciliation, not automatic execution. A complete SSE replay requires a terminated [DONE] data event and no error events. Reporting defaults to fail-open; RESPONSE_OUTBOX_STRICT=true makes a configured reporting enqueue failure return 503 (or an SSE error without [DONE]). For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity. Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules. Captured responses larger than 256 KiB are not replayable; a later retry reports an unknown outcome rather than re-executing.

Request body

ChatRequest
string
Stable identity for one intentional send; preserve it across retries. Maximum length: 256.
string
Visitor text. Required unless attachments is non-empty.
boolean
true answers text/event-stream.
Provider
Allowed values: 'openai', 'anthropic', 'gemini'.
string
Default: 'chat'.
ChatMeta
Free-form request metadata forwarded to the agent (department, custom fields, page context, sessionId, and agent/agentConfig/kb identity hints). Stored on the thread. Shape is merchant-defined.
Attachment[]
Maximum items: 5.
string
Widget session id; stored on the thread and copied into meta.sessionId.
RecoveryMessage[]
Recovery history when the referenced thread is gone (see RecoveryMessage).
string
Alternative to the x-widget-thread-token header.
string
string
object
{ orgId, agentId } identity hint; must match the widget token when present.
string
Subject for a newly created thread.
string
Continue an existing thread; omitted or unknown creates one.

Response

ChatResponse | LiveChatAcknowledgement
boolean
required
Fixed value: true.
string
required
string
required
Id the server stored for this AI reply in the thread (msg_<base36 ms>_<8 hex>). Use it as messageId for POST /api/response/feedback.
string
Present only on the response that created (or restored) the thread.
string
required
Provider
required
Allowed values: 'openai', 'anthropic', 'gemini'.
string
required
SourceCitation[]
Present only when STATESET_SHOW_SOURCES=true and the KB matched.
string
Rich message type when content is present. Allowed values: 'product_cards', 'order_cards', 'card', 'buttons', 'form'.
RichContent
Payload of a rich message (card, buttons, form, product_cards, order_cards); which keys are present depends on the message type. Mirrors RichContent in src/types/messages.ts minus client-only callbacks.
boolean
The message triggered a live-agent escalation (Gorgias ticket). Fixed value: true.

Status codes

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.
Last modified on November 13, 2026