StateSet API Docs

curl --silent --show-error --fail-with-body --no-buffer --request POST \
  --url 'https://api.example.com/api/response/stateset' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientMessageId": "string",
  "message": "Two-person tent, green — replacement for damaged pole set.",
  "stream": true,
  "provider": "openai",
  "channel": "chat",
  "meta": {
    "sessionId": "string",
    "threadMessages": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sender": "user",
        "text": "Two-person tent, green — replacement for damaged pole set.",
        "timestamp": "2026-08-31T14:22:05Z"
      }
    ]
  },
  "attachments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "size": 1,
      "type": "standard",
      "dataUrl": "string",
      "previewUrl": "string",
      "url": "https://example.com/webhooks/stateset"
    }
  ],
  "sessionId": "string",
  "threadMessages": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sender": "user",
      "text": "Two-person tent, green — replacement for damaged pole set.",
      "timestamp": "2026-08-31T14:22:05Z"
    }
  ],
  "threadToken": "YOUR_API_KEY",
  "orgId": "string",
  "agentId": "string",
  "agent": {
    "orgId": "string",
    "agentId": "string"
  },
  "subject": "Replacement tent pole set",
  "threadId": "string"
}'

{
  "ok": true,
  "threadId": "string",
  "messageId": "msg_mfu3x2k1_9c1e4a7b",
  "threadToken": "YOUR_API_KEY",
  "reply": "string",
  "provider": "openai",
  "model": "string",
  "sources": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "Replacement tent pole set",
      "url": "https://example.com/webhooks/stateset",
      "snippet": "string"
    }
  ],
  "type": "product_cards",
  "content": {
    "image": "https://cdn.example.com/products/tent-2p.jpg",
    "title": "Replacement tent pole set",
    "description": "Two-person tent, green — replacement for damaged pole set.",
    "formId": "string",
    "buttonStyle": "default",
    "layout": "scroll",
    "actions": [
      {
        "label": "Replacement tent pole set"
      }
    ],
    "buttons": [
      {
        "label": "Replacement tent pole set",
        "value": "49.00",
        "href": "https://example.com/webhooks/stateset",
        "target": "_self"
      }
    ],
    "fields": [
      {
        "name": "Two-Person Tent",
        "label": "Replacement tent pole set",
        "type": "standard",
        "placeholder": "string",
        "required": true,
        "options": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00"
          }
        ]
      }
    ],
    "submitLabel": "string",
    "headline": "Replacement tent pole set",
    "subhead": "string",
    "products": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "Replacement tent pole set",
        "price": "49.00",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "url": "https://example.com/webhooks/stateset",
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "whyItMatches": "string",
        "rating": 1.5,
        "reviewCount": 1,
        "badges": [
          "string"
        ],
        "isUpsell": true,
        "actions": [
          {
            "type": "view",
            "label": "Replacement tent pole set",
            "url": "https://example.com/webhooks/stateset",
            "value": "49.00",
            "discountCode": "5.00"
          }
        ],
        "variantOptions": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "label": "Replacement tent pole set",
            "description": "Two-person tent, green — replacement for damaged pole set.",
            "swatchColor": "string",
            "price": "49.00",
            "available": true,
            "url": "https://example.com/webhooks/stateset"
          }
        ],
        "variantSelectionLabel": "string",
        "variantSelectionPlaceholder": "string",
        "variantSelectionRequired": true,
        "variantDisplay": "select",
        "selectedVariantId": "string",
        "selectedVariantLabel": "string",
        "complementaryProducts": [
          {}
        ],
        "complementaryHeadline": "string",
        "complementaryText": "string",
        "continueShoppingAfterAdd": true
      }
    ],
    "autoAction": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "add_to_cart",
      "productId": "string",
      "quantity": 2,
      "expiresAt": "2026-08-31T14:22:05Z"
    },
    "orders": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Two-Person Tent",
        "amount": "49.00",
        "status": "pending",
        "trackingUrl": "string",
        "lineItems": [
          {
            "title": "Replacement tent pole set",
            "price": "49.00",
            "quantity": 2,
            "image": "https://cdn.example.com/products/tent-2p.jpg"
          }
        ],
        "actions": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00",
            "href": "https://example.com/webhooks/stateset",
            "target": "_self"
          }
        ]
      }
    ]
  },
  "escalated": true
}

POST

api

response

stateset

curl --silent --show-error --fail-with-body --no-buffer --request POST \
  --url 'https://api.example.com/api/response/stateset' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientMessageId": "string",
  "message": "Two-person tent, green — replacement for damaged pole set.",
  "stream": true,
  "provider": "openai",
  "channel": "chat",
  "meta": {
    "sessionId": "string",
    "threadMessages": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sender": "user",
        "text": "Two-person tent, green — replacement for damaged pole set.",
        "timestamp": "2026-08-31T14:22:05Z"
      }
    ]
  },
  "attachments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "size": 1,
      "type": "standard",
      "dataUrl": "string",
      "previewUrl": "string",
      "url": "https://example.com/webhooks/stateset"
    }
  ],
  "sessionId": "string",
  "threadMessages": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sender": "user",
      "text": "Two-person tent, green — replacement for damaged pole set.",
      "timestamp": "2026-08-31T14:22:05Z"
    }
  ],
  "threadToken": "YOUR_API_KEY",
  "orgId": "string",
  "agentId": "string",
  "agent": {
    "orgId": "string",
    "agentId": "string"
  },
  "subject": "Replacement tent pole set",
  "threadId": "string"
}'

{
  "ok": true,
  "threadId": "string",
  "messageId": "msg_mfu3x2k1_9c1e4a7b",
  "threadToken": "YOUR_API_KEY",
  "reply": "string",
  "provider": "openai",
  "model": "string",
  "sources": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "Replacement tent pole set",
      "url": "https://example.com/webhooks/stateset",
      "snippet": "string"
    }
  ],
  "type": "product_cards",
  "content": {
    "image": "https://cdn.example.com/products/tent-2p.jpg",
    "title": "Replacement tent pole set",
    "description": "Two-person tent, green — replacement for damaged pole set.",
    "formId": "string",
    "buttonStyle": "default",
    "layout": "scroll",
    "actions": [
      {
        "label": "Replacement tent pole set"
      }
    ],
    "buttons": [
      {
        "label": "Replacement tent pole set",
        "value": "49.00",
        "href": "https://example.com/webhooks/stateset",
        "target": "_self"
      }
    ],
    "fields": [
      {
        "name": "Two-Person Tent",
        "label": "Replacement tent pole set",
        "type": "standard",
        "placeholder": "string",
        "required": true,
        "options": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00"
          }
        ]
      }
    ],
    "submitLabel": "string",
    "headline": "Replacement tent pole set",
    "subhead": "string",
    "products": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "Replacement tent pole set",
        "price": "49.00",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "url": "https://example.com/webhooks/stateset",
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "whyItMatches": "string",
        "rating": 1.5,
        "reviewCount": 1,
        "badges": [
          "string"
        ],
        "isUpsell": true,
        "actions": [
          {
            "type": "view",
            "label": "Replacement tent pole set",
            "url": "https://example.com/webhooks/stateset",
            "value": "49.00",
            "discountCode": "5.00"
          }
        ],
        "variantOptions": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "label": "Replacement tent pole set",
            "description": "Two-person tent, green — replacement for damaged pole set.",
            "swatchColor": "string",
            "price": "49.00",
            "available": true,
            "url": "https://example.com/webhooks/stateset"
          }
        ],
        "variantSelectionLabel": "string",
        "variantSelectionPlaceholder": "string",
        "variantSelectionRequired": true,
        "variantDisplay": "select",
        "selectedVariantId": "string",
        "selectedVariantLabel": "string",
        "complementaryProducts": [
          {}
        ],
        "complementaryHeadline": "string",
        "complementaryText": "string",
        "continueShoppingAfterAdd": true
      }
    ],
    "autoAction": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "add_to_cart",
      "productId": "string",
      "quantity": 2,
      "expiresAt": "2026-08-31T14:22:05Z"
    },
    "orders": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Two-Person Tent",
        "amount": "49.00",
        "status": "pending",
        "trackingUrl": "string",
        "lineItems": [
          {
            "title": "Replacement tent pole set",
            "price": "49.00",
            "quantity": 2,
            "image": "https://cdn.example.com/products/tent-2p.jpg"
          }
        ],
        "actions": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00",
            "href": "https://example.com/webhooks/stateset",
            "target": "_self"
          }
        ]
      }
    ]
  },
  "escalated": true
}

Native human takeover may return a JSON liveChat acknowledgement even with stream=true. With clientMessageId and session identity, complete replies replay for ten minutes with X-Idempotent-Replay: true. 409 message_outcome_unknown requires conversation refresh and reconciliation, not automatic execution. A complete SSE replay requires a terminated [DONE] data event and no error events. Reporting defaults to fail-open; RESPONSE_OUTBOX_STRICT=true makes a configured reporting enqueue failure return 503 (or an SSE error without [DONE]). For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity. Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules. Captured responses larger than 256 KiB are not replayable; a later retry reports an unknown outcome rather than re-executing.

Request body

ChatRequest

string

Stable identity for one intentional send; preserve it across retries. Maximum length: 256.

string

Visitor text. Required unless attachments is non-empty.

boolean

true answers text/event-stream.

Provider

Allowed values: 'openai', 'anthropic', 'gemini'.

string

Default: 'chat'.

ChatMeta

Free-form request metadata forwarded to the agent (department, custom fields, page context, sessionId, and agent/agentConfig/kb identity hints). Stored on the thread. Shape is merchant-defined.

Show ChatMeta

string

RecoveryMessage[]

Show RecoveryMessage

string

required

Allowed values: 'user', 'ai'.

string

required

string

Attachment[]

Maximum items: 5.

Show Attachment

string

required

integer

required

Maximum: 10485760.

string

required

string

data:<mime>;base64,<payload>.

string,null

string

Public URL of an already uploaded image (read for vision providers).

string

Widget session id; stored on the thread and copied into meta.sessionId.

RecoveryMessage[]

Recovery history when the referenced thread is gone (see RecoveryMessage).

Show RecoveryMessage

string

required

Allowed values: 'user', 'ai'.

string

required

string

Alternative to the x-widget-thread-token header.

string

object

{ orgId, agentId } identity hint; must match the widget token when present.

Show agent

string

Subject for a newly created thread.

string

Continue an existing thread; omitted or unknown creates one.

Response

ChatResponse | LiveChatAcknowledgement

boolean

required

Fixed value: true.

string

required

string

required

Id the server stored for this AI reply in the thread (msg_<base36 ms>_<8 hex>). Use it as messageId for POST /api/response/feedback.

string

Present only on the response that created (or restored) the thread.

string

required

Provider

required

Allowed values: 'openai', 'anthropic', 'gemini'.

string

required

SourceCitation[]

Present only when STATESET_SHOW_SOURCES=true and the KB matched.

Show SourceCitation

string

required

string

required

string

required

string

Up to 220 characters of the document.

string

Rich message type when content is present. Allowed values: 'product_cards', 'order_cards', 'card', 'buttons', 'form'.

RichContent

Payload of a rich message (card, buttons, form, product_cards, order_cards); which keys are present depends on the message type. Mirrors RichContent in src/types/messages.ts minus client-only callbacks.

Show RichContent

string

Allowed values: 'default', 'pill'.

string

Allowed values: 'scroll', 'stack'.

object[]

Show actions

string

required

object[]

Show buttons

string

required

string

Allowed values: '_self', '_blank'.

object[]

Show fields

string

required

string

required

string

boolean

object[]

string

ProductCard[]

Show ProductCard

string

required

string

required

string

number

integer

string[]

boolean

ProductAction[]

ProductVariantOption[]

string

boolean

string

Allowed values: 'select', 'swatches'.

string

ProductCard[]

string

boolean

object

Show autoAction

string

required

string

required

Fixed value: 'add_to_cart'.

string

required

integer

required

string (date-time)

required

OrderCard[]

Show OrderCard

string

required

string

required

string

object[]

boolean

The message triggered a live-agent escalation (Gorgias ticket). Fixed value: true.

Status codes

Code	Meaning
`200`	Assistant reply. `application/json` when `stream` is falsy; `text/event-stream` when
`stream: true` (see `SSEStream`).
`400`	No message or attachments, attachments rejected, or malformed JSON
`401`	Widget token missing, malformed, expired, from the future, or badly signed
`403`	Thread capability missing/wrong, thread owner mismatch, or token identity mismatch
`409`	idempotency_conflict, message_in_progress, message_outcome_unknown, or thread_busy
`413`	Body over the JSON limit, or an attachment over 10 MB
`429`	Too many requests for this IP (scoped by verified org/agent)
`500`	Provider failure. The chat handler answers `{ error: <provider error message>, type }`
(a human-readable message, not a code) or `{ error: '<PROVIDER>_API_KEY is not set.' }`
when the selected provider has no key. The request and the provider key are validated
before a thread is restored or created; when a later failure happens on a thread this
request created or restored, the body also carries `threadId` and the one-time
`threadToken`. Errors thrown before the handler answer `{ error: internal_error,
requestId }`. On an SSE stream the failure is emitted as an` error` event instead and
the stream ends.
`503`	Strict response-reporting queue unavailable/full, execution store or persistence failure. The default reporting mode logs/counts enqueue loss while permitting the reply. An interrupted stream can emit an error without [DONE].

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.

curl --silent --show-error --fail-with-body --no-buffer --request POST \
  --url 'https://api.example.com/api/response/stateset' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientMessageId": "string",
  "message": "Two-person tent, green — replacement for damaged pole set.",
  "stream": true,
  "provider": "openai",
  "channel": "chat",
  "meta": {
    "sessionId": "string",
    "threadMessages": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sender": "user",
        "text": "Two-person tent, green — replacement for damaged pole set.",
        "timestamp": "2026-08-31T14:22:05Z"
      }
    ]
  },
  "attachments": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "size": 1,
      "type": "standard",
      "dataUrl": "string",
      "previewUrl": "string",
      "url": "https://example.com/webhooks/stateset"
    }
  ],
  "sessionId": "string",
  "threadMessages": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sender": "user",
      "text": "Two-person tent, green — replacement for damaged pole set.",
      "timestamp": "2026-08-31T14:22:05Z"
    }
  ],
  "threadToken": "YOUR_API_KEY",
  "orgId": "string",
  "agentId": "string",
  "agent": {
    "orgId": "string",
    "agentId": "string"
  },
  "subject": "Replacement tent pole set",
  "threadId": "string"
}'

{
  "ok": true,
  "threadId": "string",
  "messageId": "msg_mfu3x2k1_9c1e4a7b",
  "threadToken": "YOUR_API_KEY",
  "reply": "string",
  "provider": "openai",
  "model": "string",
  "sources": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "Replacement tent pole set",
      "url": "https://example.com/webhooks/stateset",
      "snippet": "string"
    }
  ],
  "type": "product_cards",
  "content": {
    "image": "https://cdn.example.com/products/tent-2p.jpg",
    "title": "Replacement tent pole set",
    "description": "Two-person tent, green — replacement for damaged pole set.",
    "formId": "string",
    "buttonStyle": "default",
    "layout": "scroll",
    "actions": [
      {
        "label": "Replacement tent pole set"
      }
    ],
    "buttons": [
      {
        "label": "Replacement tent pole set",
        "value": "49.00",
        "href": "https://example.com/webhooks/stateset",
        "target": "_self"
      }
    ],
    "fields": [
      {
        "name": "Two-Person Tent",
        "label": "Replacement tent pole set",
        "type": "standard",
        "placeholder": "string",
        "required": true,
        "options": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00"
          }
        ]
      }
    ],
    "submitLabel": "string",
    "headline": "Replacement tent pole set",
    "subhead": "string",
    "products": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "Replacement tent pole set",
        "price": "49.00",
        "image": "https://cdn.example.com/products/tent-2p.jpg",
        "url": "https://example.com/webhooks/stateset",
        "description": "Two-person tent, green — replacement for damaged pole set.",
        "whyItMatches": "string",
        "rating": 1.5,
        "reviewCount": 1,
        "badges": [
          "string"
        ],
        "isUpsell": true,
        "actions": [
          {
            "type": "view",
            "label": "Replacement tent pole set",
            "url": "https://example.com/webhooks/stateset",
            "value": "49.00",
            "discountCode": "5.00"
          }
        ],
        "variantOptions": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "label": "Replacement tent pole set",
            "description": "Two-person tent, green — replacement for damaged pole set.",
            "swatchColor": "string",
            "price": "49.00",
            "available": true,
            "url": "https://example.com/webhooks/stateset"
          }
        ],
        "variantSelectionLabel": "string",
        "variantSelectionPlaceholder": "string",
        "variantSelectionRequired": true,
        "variantDisplay": "select",
        "selectedVariantId": "string",
        "selectedVariantLabel": "string",
        "complementaryProducts": [
          {}
        ],
        "complementaryHeadline": "string",
        "complementaryText": "string",
        "continueShoppingAfterAdd": true
      }
    ],
    "autoAction": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "add_to_cart",
      "productId": "string",
      "quantity": 2,
      "expiresAt": "2026-08-31T14:22:05Z"
    },
    "orders": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Two-Person Tent",
        "amount": "49.00",
        "status": "pending",
        "trackingUrl": "string",
        "lineItems": [
          {
            "title": "Replacement tent pole set",
            "price": "49.00",
            "quantity": 2,
            "image": "https://cdn.example.com/products/tent-2p.jpg"
          }
        ],
        "actions": [
          {
            "label": "Replacement tent pole set",
            "value": "49.00",
            "href": "https://example.com/webhooks/stateset",
            "target": "_self"
          }
        ]
      }
    ]
  },
  "escalated": true
}

Last modified on November 13, 2026

Overview

Chat

Threads

Catalog

Cart

Settings

Feedback

Telemetry

Review

Analytics

System

Webhooks

Live chat

Admin

Alias of POST /api/chat

Request body

Response

Status codes

Using this contract