Widget messages API

Visitor messages from the web widget are posted to this endpoint. Supports synchronous JSON and SSE streaming.

Endpoint

POST /api/v1/widget/messages

Auth	Mechanism
Deployment	`deployment_id` in body
Domain	`Origin` header must match allowlist
Identity (optional)	`Authorization: Bearer <jwt>` when JWT verification is enabled

No organization API key is used from the browser.

Send message (sync)

{
  "deployment_id": "dep_abc123",
  "conversation_id": "conv_8mN4pQ1r",
  "content": "Do you ship to Canada?"
}

Omit conversation_id to start a new conversation. The response includes conversation_id for follow-up messages.

Response:

{
  "id": "msg_4pQ8rS2t",
  "conversation_id": "conv_8mN4pQ1r",
  "role": "assistant",
  "content": "Yes, we ship to all Canadian provinces…",
  "citations": [],
  "created_at": "2026-07-16T10:12:00Z"
}

Streaming (SSE)

Set stream: true:

{
  "deployment_id": "dep_abc123",
  "conversation_id": "conv_8mN4pQ1r",
  "content": "Show me your summer offers",
  "stream": true
}

Response Content-Type: text/event-stream.

SSE events

Event	Purpose
`step_message`	Progress text, e.g. “Searching knowledge base…”
`tool_call`	Tool invocation started
`tool_result`	Tool completed
`done`	Final message with `content` and optional `rich_content`
`error`	Terminal failure

Full payload reference: Widget SSE events.

Example stream:

event: step_message
data: {"message":"Thinking…"}

event: tool_call
data: {"name":"get_offers","message":"Running get_offers…"}

event: tool_result
data: {"name":"get_offers","success":true}

event: done
data: {"content":"Here are our summer offers:","rich_content":{"type":"carousel","items":[…]}}

JWT identity

When the deployment requires identity verification, include a signed JWT:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

See JWT embed verification.

Rate limits

Widget message requests share the Widget rate limit bucket (120 req/min per deployment). Heavy traffic may also hit per-visitor throttles.