> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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…

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`

<ParamField body="subject" type="string">
  Optional conversation title
</ParamField>

<ParamField body="message" type="string" required>
  User input text
</ParamField>

<ParamField body="attachments" type="object[]" />

<ParamField body="meta" type="object">
  `&#123; department, customFields &#125;` from widget props
</ParamField>

<ParamField body="sessionId" type="string">
  Widget session identifier
</ParamField>

<ParamField body="channel" type="string">
  Defaults to `chat`
</ParamField>

<ParamField body="threadId" type="string">
  Existing thread id, if any
</ParamField>

<ParamField body="stream" type="boolean">
  When true the server should stream SSE events and end with `[DONE]`
</ParamField>

<ParamField body="provider" type="string">
  Optional override: `openai`, `anthropic` or `gemini`
</ParamField>

<ParamField body="orgId" type="string">
  Optional org id, used to fetch rules and knowledge base
</ParamField>

<ParamField body="agentId" type="string">
  Optional agent id, used to fetch rules
</ParamField>

<ParamField body="kbCollection" type="string">
  Optional knowledge-base collection override
</ParamField>

<ParamField body="kbApiKey" type="string">
  Optional KB API key override — avoid sending client-side in production
</ParamField>

<ParamField body="kbTopK" type="number">
  KB retrieval limit (default 3)
</ParamField>

<ParamField body="kbScoreThreshold" type="number">
  KB similarity threshold (default 0.5)
</ParamField>

### Response

`ChatResponse`

<ResponseField name="ok" type="boolean" required />

<ResponseField name="reply" type="string" required>
  The assistant reply, rendered as markdown
</ResponseField>

<ResponseField name="threadId" type="string" />

<ResponseField name="suggestions" type="string[]" />

<ResponseField name="provider" type="string" />

<ResponseField name="model" type="string" />

<ResponseField name="toolCalls" type="object[]" />

<ResponseField name="sources" type="object[]">
  <Expandable title="sources">
    <ResponseField name="title" type="string" />

    <ResponseField name="url" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="outcomes" type="Outcome[]">
  <Expandable title="Outcome">
    <ResponseField name="name" type="string">
      e.g. `order.cancelled`, `cart.added`, `checkout.started`, `purchase.completed`
    </ResponseField>

    <ResponseField name="resourceType" type="string" />

    <ResponseField name="resourceId" type="string" />

    <ResponseField name="quantity" type="number" />

    <ResponseField name="amount" type="number">
      Minor units
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Minor units
    </ResponseField>

    <ResponseField name="currency" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="type" type="string">
  Rich message type: `product_cards` or `order_cards`
</ResponseField>

<ResponseField name="content" type="object">
  Payload for the rich message type

  <Expandable title="content">
    <ResponseField name="headline" type="string" />

    <ResponseField name="products" type="object[]">
      <Expandable title="products">
        <ResponseField name="id" type="string" />

        <ResponseField name="title" type="string" />

        <ResponseField name="price" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="orders" type="object[]" />
  </Expandable>
</ResponseField>

### Status codes

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

<RequestExample>
  ```bash cURL theme={null}
  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
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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": [
        {}
      ]
    }
  }
  ```
</ResponseExample>