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 reference for the onsite chat widget. To get it running first, start with the Onsite Chat Quickstart.

What it ships with

AI ready — OpenAI, Anthropic, and Gemini integration with streaming, tool feedback, and source citations.
Rich UI — Markdown with syntax highlighting, reactions, exports, forms, and programmable actions.
Mobile ready — responsive fullscreen with safe-area handling for modern iPhone Safari.
Operations ready — built-in record views for orders, products, subscriptions, returns, and exchanges.
Global ready — locale packs, translation overrides, automatic RTL layout.
Developer friendly — UMD bundle, type definitions, mock and AI dev servers, Docker image.

Hosting options

Approach	When to use	Notes
Static CDN	You already have APIs and just need the bundle	Serve `chat-widget.css` and `chat-widget.bundle.js` with long cache TTLs
Docker + Nginx	Easiest full-stack demo	`docker build -t chat-widget . && docker run -p 8080:80 chat-widget`
Edge function	Injecting the snippet across multiple sites	Host the bundle on a CDN and lazy-load via script tag
React / Vue app	Embedding inside an SPA	Use the UMD API (`window.ChatWidget`) or wrap it in a component

Production CDN

The recommended production setup is Cloud Storage plus Cloud CDN with versioned assets. One-time setup creates the bucket, CDN backend, URL map, HTTPS proxy, and global IP:

scripts/setup-cdn-gcp.sh \
  --project stateset-network \
  --bucket stateset-chat-cdn \
  --domain stateset.chat \
  --location US

Then in DNS for stateset.chat, create an A record pointing at the global IP the script prints, and wait for the managed SSL certificate to become ACTIVE — that can take 15–60 minutes. Publish a version:

npm run build
scripts/publish-cdn.sh --bucket stateset-chat-cdn --version 1.0.0

Embed the versioned assets:

<link rel="stylesheet" href="https://stateset.chat/chat-widget.v1.0.0.css" />
<script src="https://stateset.chat/chat-widget.bundle.v1.0.0.js"></script>

Versioned filenames are what make long cache TTLs safe. Publish a new version rather than overwriting one — then you rarely need cache invalidation at all:

gcloud compute url-maps invalidate-cdn-cache stateset-chat-cdn-map --path "/*"

Backend options

Server	Suitable for
Mock server (`dev-server.js`)	Demos and UI work. No auth, no persistence
AI server (`server-openai.js`)	OpenAI/Anthropic/Gemini completions
Your API	Production — expose `POST /api/chat` plus optional thread CRUD; the full contract is the Chat Widget API reference

The bundled AI server has no authentication, logging, or database. Add all three before putting it in front of customers — it exists to prove the wiring, not to run production traffic.

Hardening

Put your API behind OAuth/JWT or signed session cookies.
Rate limit inbound chat requests per IP and session at the edge.
Validate and sanitize user uploads before echoing them in the UI.
Sanitize AI-generated markdown — the widget uses DOMPurify by default.
Set Content-Security-Policy headers in nginx.conf or at your hosting platform.

Secrets and runtime

Keep .env out of version control, hold provider keys in a secret manager (AWS Secrets Manager, Doppler, Vault), and pin Node via .nvmrc or your host’s runtime setting — the widget requires 20.17+.

Revenue capture v2

For the ResponseCX lead-qualifier rollout, the bundle exports helpers that turn a public config response into mountable widget props, so configuration lives server-side rather than in the embed snippet.

<script>
  async function bootRevenueCaptureWidget() {
    const widgetToken = 'SIGNED_PUBLIC_WIDGET_TOKEN';
    const response = await fetch(
      `/api/public/widget/v2/config?token=${encodeURIComponent(widgetToken)}`
    );
    const config = await response.json();

    const props = window.ChatWidget.createRevenueCaptureMountProps({
      config,
      widgetAuthToken: widgetToken,
      overrides: {
        position: 'bottom-right',
        calendlyUrl: 'https://calendly.com/stateset/responsecx-demo',
      },
    });

    window.ChatWidget.mount({ container: document.getElementById('chat'), props });
  }

  bootRevenueCaptureWidget();
</script>

Helpers:

window.ChatWidget.buildRevenueCapturePageContext(...)
window.ChatWidget.createRevenueCaptureMountProps(...)
window.ChatWidget.mountRevenueCaptureWidget(...)

The config route is GET /api/public/widget/v2/config?token=<signed-widget-token>. For a local end-to-end mock of the public contract, run npm run dev and open /widget/v2/demo.html.

The token in the embed is a signed public widget token — it is visible to anyone who views source, and is meant to be. Do not put a private API key in the embed snippet.

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

Response Chat Widget

What it ships with

Hosting options

Production CDN

Backend options

Hardening

Secrets and runtime

Revenue capture v2

​What it ships with

​Hosting options

​Production CDN

​Backend options

​Hardening

​Secrets and runtime

​Revenue capture v2

​Related

What it ships with

Hosting options

Production CDN

Backend options

Hardening

Secrets and runtime

Revenue capture v2

Related