Send a message and get a reply

The one endpoint the widget requires. With stream: true, respond with Content-Type: text/event-stream, one JSON object per data: line (see the SseEvent shape…

POST /api/chat

cURL

curl --request POST \
  --url 'https://api.example.com/api/chat' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "Replacement tent pole set",
  "message": "Two-person tent, green — replacement for damaged pole set.",
  "attachments": [
    {
      "name": "Two-Person Tent",
      "type": "standard",
      "size": 1.5
    }
  ],
  "meta": {
    "department": "string",
    "customFields": {},
    "agent": {
      "orgId": "string",
      "agentId": "string"
    }
  },
  "sessionId": "string",
  "channel": "string",
  "threadId": "string",
  "stream": true,
  "provider": "string",
  "orgId": "string",
  "agentId": "string",
  "kbCollection": "string",
  "kbApiKey": "YOUR_API_KEY",
  "kbTopK": 1.5,
  "kbScoreThreshold": 7.5
}'

200

{
  "ok": true,
  "reply": "string",
  "threadId": "string",
  "suggestions": [
    "string"
  ],
  "provider": "string",
  "model": "string",
  "toolCalls": [
    {}
  ],
  "sources": [
    {
      "title": "Replacement tent pole set",
      "url": "https://example.com/webhooks/stateset"
    }
  ],
  "outcomes": [
    {
      "name": "Two-Person Tent",
      "resourceType": "string",
      "resourceId": "string",
      "quantity": 2,
      "amount": 49,
      "revenue": 49,
      "currency": "USD"
    }
  ],
  "type": "standard",
  "content": {
    "headline": "Replacement tent pole set",
    "products": [
      {
        "id": null,
        "title": null,
        "price": null
      }
    ],
    "orders": [
      {}
    ]
  }
}

The one endpoint the widget requires. With stream: true, respond with Content-Type: text/event-stream, one JSON object per data: line (see the SseEvent shape in the overview), and finish with data: [DONE]. Without it, respond with the JSON body below.

Request body

ChatRequest

subject · string

Optional conversation title

message · string · required

User input text

attachments · object[]

meta · object

{ department, customFields } from widget props

sessionId · string

Widget session identifier

channel · string

Defaults to chat

threadId · string

Existing thread id, if any

stream · boolean

When true the server should stream SSE events and end with [DONE]

provider · string

Optional override: openai, anthropic or gemini

orgId · string

Optional org id, used to fetch rules and knowledge base

agentId · string

Optional agent id, used to fetch rules

kbCollection · string

Optional knowledge-base collection override

kbApiKey · string

Optional KB API key override — avoid sending client-side in production

kbTopK · number

KB retrieval limit (default 3)

kbScoreThreshold · number

KB similarity threshold (default 0.5)

Response

ChatResponse

ok · boolean · required

reply · string · required

The assistant reply, rendered as markdown

threadId · string

suggestions · string[]

provider · string

model · string

toolCalls · object[]

sources · object[]

Show sources

title · string

url · string

outcomes · Outcome[]

Show Outcome

name · string

e.g. order.cancelled, cart.added, checkout.started, purchase.completed

resourceType · string

resourceId · string

quantity · number

amount · number

Minor units

revenue · number

Minor units

currency · string

type · string

Rich message type: product_cards or order_cards

content · object

Payload for the rich message type

Show content

headline · string

products · object[]

Show products

id · string

title · string

price · string

orders · object[]

Status codes

Code	Meaning
200	OK
400	Error
401	Error

cURL

curl --request POST \
  --url 'https://api.example.com/api/chat' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "Replacement tent pole set",
  "message": "Two-person tent, green — replacement for damaged pole set.",
  "attachments": [
    {
      "name": "Two-Person Tent",
      "type": "standard",
      "size": 1.5
    }
  ],
  "meta": {
    "department": "string",
    "customFields": {},
    "agent": {
      "orgId": "string",
      "agentId": "string"
    }
  },
  "sessionId": "string",
  "channel": "string",
  "threadId": "string",
  "stream": true,
  "provider": "string",
  "orgId": "string",
  "agentId": "string",
  "kbCollection": "string",
  "kbApiKey": "YOUR_API_KEY",
  "kbTopK": 1.5,
  "kbScoreThreshold": 7.5
}'

200

{
  "ok": true,
  "reply": "string",
  "threadId": "string",
  "suggestions": [
    "string"
  ],
  "provider": "string",
  "model": "string",
  "toolCalls": [
    {}
  ],
  "sources": [
    {
      "title": "Replacement tent pole set",
      "url": "https://example.com/webhooks/stateset"
    }
  ],
  "outcomes": [
    {
      "name": "Two-Person Tent",
      "resourceType": "string",
      "resourceId": "string",
      "quantity": 2,
      "amount": 49,
      "revenue": 49,
      "currency": "USD"
    }
  ],
  "type": "standard",
  "content": {
    "headline": "Replacement tent pole set",
    "products": [
      {
        "id": null,
        "title": null,
        "price": null
      }
    ],
    "orders": [
      {}
    ]
  }
}