StateSet API Docs

Using the hosted ResponseCX Widget Builder and Chat Desk? Follow Widget to desk for the hosted v2 loader, human handoff, and transcript verification. This page covers the standalone widget integration; its custom backend is not automatically connected to the desk.

The Response Chat Widget is a production-ready, AI-powered chat widget you drop into any web application. This page gets it on your site and talking to a backend. The widget ships as a UMD bundle. Include React, the stylesheet, and the bundle, then mount it into any container:

<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<link rel="stylesheet" href="https://stateset.chat/vX.Y.Z/chat-widget.css" />
<script src="https://stateset.chat/vX.Y.Z/chat-widget.bundle.js"></script>

<div id="chat"></div>

<script>
  const api = window.ChatWidget.mount({
    container: document.getElementById('chat'),
    props: {
      companyName: 'Acme Inc.',
      agentName: 'AI Assistant',
      messageEndpoint: '/api/chat',
      threadCreateEndpoint: '/api/threads',
      provider: 'openai',
      enableStreaming: true,
      enableToolVisualization: true,
      enableSourceCitations: true,
      enableRichMessages: true,
    },
  });
</script>

Pin a version in the CDN URL — replace vX.Y.Z with a real release. Pointing at a floating “latest” means a widget upgrade ships to your production site without you deploying anything.

mount() returns a control surface:

api.open();
api.close();
api.toggle();

provider accepts openai, anthropic, or gemini.

2. Wire up your backend

With messageEndpoint set, the widget POSTs JSON in this shape:

{
  "subject": "Optional conversation subject",
  "message": "Customer message text",
  "attachments": [{ "name": "screenshot.png", "type": "image/png", "size": 12345 }],
  "meta": { "department": "Support", "customFields": {} },
  "sessionId": "optional-session",
  "source": "response-chat-widget",
  "channel": "web",
  "threadId": "abc123",
  "provider": "openai"
}

Your endpoint should return an object the widget can render. If your API has a different shape, you don’t need to change it — override both directions:

Hook	Purpose
`buildMessagePayload(payload, outgoingMessage)`	Reshape the outgoing request
`parseResponse(response)`	Map your response to `{ text, suggestions, threadId?, toolCalls?, sources? }`

Threads

Provide threadEndpoint and threadId to load history. The widget issues GET {endpoint}?threadId={id} with optional bearer auth. Full CRUD is available via threadCreateEndpoint, threadUpdateEndpoint, and threadDeleteEndpoint, with buildThreadRequest, buildThreadUrl, buildThreadUpdateUrl, and buildThreadDeleteUrl for custom URL shapes.

3. Run it locally first

npm install
cp env.example .env       # set OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY

npm run dev               # mock backend + demo widget → http://localhost:3000
npm run dev:ai            # talk to real models (needs an API key)

Node.js 20.17.0+ is required and enforced in CI.

Command	Purpose
`npm run dev`	Mock server with streaming and ChatKit simulations
`npm run dev:ai`	AI-powered server (OpenAI/Anthropic/Gemini)
`npm run build`	Produces `public/chat-widget.bundle.js` and CSS
`npm test`	Jest suite (jsdom + Testing Library)
`npm run validate`	Format check → lint → test, as CI runs it

Start against the mock server. It exercises streaming, tool visualization, and citations without spending API credits or needing a working backend.

4. Show commerce records

The widget header carries tabs for Chat, Orders, Products, Subscriptions, Returns, and Exchanges, driven by the records prop:

window.ChatWidget.mount({
  container: document.getElementById('chat'),
  props: {
    records: {
      products: [{
        id: 'SKU-44819',
        name: 'Luna Smart Bottle',
        status: 'In Stock',
        price: '$89.00',
        stock: 182,
        rating: 4.8,
        badges: ['Top seller'],
      }],
      orders: [{
        id: 'ORD-9001',
        status: 'Processing',
        amount: '$199.00',
        customer: 'Jordan Lee',
        summary: 'Home gym starter kit',
        metrics: [{ label: 'Items', value: '4' }],
        nextAction: 'Confirm inventory with warehouse',
      }],
      returns: [], subscriptions: [], exchanges: [],
    },
  },
});

Each category renders status badges, metrics, and summary cards automatically. Orders, returns, exchanges, and subscriptions have a List mode; products support List and Carousel.

Omit records entirely and sample data is shown, so the UI never looks empty in a demo. Make sure you pass real data before going to production — otherwise customers see the samples.

Feature flags

Prop	Effect
`enableStreaming`	Token-by-token streaming responses
`enableToolVisualization`	Shows tool calls as the agent makes them
`enableSourceCitations`	Renders source citations under answers
`enableRichMessages`	Markdown, syntax highlighting, forms, and actions

Other capabilities: reactions, transcript export, programmable actions, responsive fullscreen with iPhone safe-area handling, and built-in locale packs with translation overrides and automatic RTL layout.

Next steps

Widget reference

Configuration, revenue capture v2, and deployment.

Chat Widget API

The contract your messageEndpoint implements — request, reply, and the SSE event stream.

Response Public API

Build the agent behind the chat.

Last modified on September 20, 2026

Get started

Build your first integration

Operate and improve

Resources and support

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Onsite Chat Quickstart

1. Embed the widget

2. Wire up your backend

Threads

3. Run it locally first

4. Show commerce records

Feature flags

Next steps

Widget reference

Chat Widget API

Response Public API

​1. Embed the widget

​2. Wire up your backend

​Threads

​3. Run it locally first

​4. Show commerce records

​Feature flags

​Next steps

Widget reference

Chat Widget API

Response Public API

1. Embed the widget

2. Wire up your backend

Threads

3. Run it locally first

4. Show commerce records

Feature flags

Next steps