Chat API

Send a message


POST /api/chat

Required headers:

Content-Type: application/json
X-Widget-Publishable-Key: <key>
X-Visitor-Id: <visitor-id>

Request body:


{
  "messages": [
    { "role": "user", "content": "What is your refund policy?" }
  ],
  "conversationId": "optional-server-session-id",
  "visitId": "optional-client-visit-id",
  "visitorId": "optional-if-header-is-set",
  "pageUrl": "https://example.com/pricing",
  "pageTitle": "Pricing",
  "timeZone": "Australia/Hobart"
}

The final item in messages must contain a non-empty user message. The current maximum is 4000 characters. A custom client may send recent user and assistant messages, but Engine 64 resolves the authoritative server conversation and limits the amount of history used for a turn.

Conversation identity

Create a random visitorId and keep it for this widget in the browser.
Create a new random visitId for a new website visit. Tabs in the same active visit may share it.
Omit conversationId on the first turn. Read X-Conversation-Id from the response and send it on later turns in that visit.
Do not reuse an old conversationId to force a previous visit to resume.

Engine 64 validates the identifiers together, retrieves relevant sources, runs chat safety checks, streams the answer, and stores the turn.

Presence heartbeat


POST /api/chat/presence

Once a conversation has started, send periodic heartbeats while the visitor is present:


{
  "conversationId": "server-session-id",
  "visitId": "client-visit-id",
  "visitorId": "visitor-id",
  "pageUrl": "https://example.com/pricing"
}

Use the same publishable-key and visitor-ID headers as chat. A successful response is { "success": true, "conversationId": "..." }. An expired or mismatched visit returns HTTP 200 with { "success": false, "expired": true }; start a new visit rather than retrying the old IDs.

Response

POST /api/chat returns HTTP 200 with a streaming response and the headers described in Authentication and Headers. Preserve the IDs before consuming or closing the stream.

Error Responses

400: missing user message, visitor ID, or required presence fields
401: invalid/missing widget publishable key
403: domain not allowed or service unavailable for the workspace
404: agent not found
413: message too long
429: rate limit or usage quota reached
500: the chat pipeline could not complete the turn