Chat API

Endpoint:

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"
}

Behavior

• Validates latest user message and length limits
• Resolves the active chat session by exact conversationId or by visitId
• Retrieves relevant source chunks
• Streams assistant response text
• Persists messages and session metadata

conversationId is the server-side chat session id returned by the API.

visitId is a client-generated website-visit identifier. New visits should send a new visitId instead of reusing the previous one.

Presence Heartbeat

POST /api/chat/presence

Send periodic heartbeats for active visits once a conversation has started:

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

Success Response

• HTTP 200 streaming text response
• Includes conversation and source headers

Error Responses

• 400: missing user message or visitor id
• 401: invalid/missing widget publishable key
• 403: domain not allowed
• 404: agent not found
• 413: message too long
• 429: rate limited