StateSet API Docs

curl --request POST \
  --url 'https://api.example.com/api/chat' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "string",
  "message": "string",
  "attachments": [
    {
      "name": "string",
      "type": "string",
      "size": 1
    }
  ],
  "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": "string",
  "kbTopK": 1,
  "kbScoreThreshold": 1
}'

{
  "ok": true,
  "reply": "string",
  "threadId": "string",
  "suggestions": [
    "string"
  ],
  "provider": "string",
  "model": "string",
  "toolCalls": [
    {}
  ],
  "sources": [
    {
      "title": "string",
      "url": "string"
    }
  ],
  "outcomes": [
    {
      "name": "string",
      "resourceType": "string",
      "resourceId": "string",
      "quantity": 1,
      "amount": 1,
      "revenue": 1,
      "currency": "string"
    }
  ],
  "type": "string",
  "content": {
    "headline": "string",
    "products": [
      {
        "id": null,
        "title": null,
        "price": null
      }
    ],
    "orders": [
      {}
    ]
  }
}

POST

api

chat

curl --request POST \
  --url 'https://api.example.com/api/chat' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "string",
  "message": "string",
  "attachments": [
    {
      "name": "string",
      "type": "string",
      "size": 1
    }
  ],
  "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": "string",
  "kbTopK": 1,
  "kbScoreThreshold": 1
}'

{
  "ok": true,
  "reply": "string",
  "threadId": "string",
  "suggestions": [
    "string"
  ],
  "provider": "string",
  "model": "string",
  "toolCalls": [
    {}
  ],
  "sources": [
    {
      "title": "string",
      "url": "string"
    }
  ],
  "outcomes": [
    {
      "name": "string",
      "resourceType": "string",
      "resourceId": "string",
      "quantity": 1,
      "amount": 1,
      "revenue": 1,
      "currency": "string"
    }
  ],
  "type": "string",
  "content": {
    "headline": "string",
    "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

string

Optional conversation title

string

required

User input text

object[]

object

{ department, customFields } from widget props

string

Widget session identifier

string

Defaults to chat

string

Existing thread id, if any

boolean

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

string

Optional override: openai, anthropic or gemini

string

Optional org id, used to fetch rules and knowledge base

string

Optional agent id, used to fetch rules

string

Optional knowledge-base collection override

string

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

number

KB retrieval limit (default 3)

number

KB similarity threshold (default 0.5)

Response

ChatResponse

boolean

required

string

required

The assistant reply, rendered as markdown

string

string[]

string

object[]

Show sources

string

Outcome[]

Show Outcome

string

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

string

number

Minor units

number

Minor units

string

Rich message type: product_cards or order_cards

object

Payload for the rich message type

Show content

string

object[]

Show products

string

object[]

Status codes

Code	Meaning
`200`	OK
`400`	Error
`401`	Error

curl --request POST \
  --url 'https://api.example.com/api/chat' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "string",
  "message": "string",
  "attachments": [
    {
      "name": "string",
      "type": "string",
      "size": 1
    }
  ],
  "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": "string",
  "kbTopK": 1,
  "kbScoreThreshold": 1
}'

{
  "ok": true,
  "reply": "string",
  "threadId": "string",
  "suggestions": [
    "string"
  ],
  "provider": "string",
  "model": "string",
  "toolCalls": [
    {}
  ],
  "sources": [
    {
      "title": "string",
      "url": "string"
    }
  ],
  "outcomes": [
    {
      "name": "string",
      "resourceType": "string",
      "resourceId": "string",
      "quantity": 1,
      "amount": 1,
      "revenue": 1,
      "currency": "string"
    }
  ],
  "type": "string",
  "content": {
    "headline": "string",
    "products": [
      {
        "id": null,
        "title": null,
        "price": null
      }
    ],
    "orders": [
      {}
    ]
  }
}

Overview

Chat

Threads

Catalog

Cart

Settings

Telemetry

Review

Analytics

System

Admin

Send a message and get a reply

Request body

Response

Status codes

​Request body

​Response

​Status codes

Request body

Response

Status codes