Docs Getting started

Getting started

Add the chat widget with one script tag, then run your first AI conversation. It takes about five minutes.

Updated 21 November 2026Widget v0.1

Before you start

You need a workspace ID. It looks like ws_ followed by letters and digits.

Sign-up opens at launch in December 2026. Until then, use the demo workspace ws_demo to try every step on this page. It answers from ChatSupportHQ's own help content, so ask it about our plans and features.

Please use ws_demo on a test page only, not on a live site. It has a small daily AI budget shared by everyone.

Add the widget

Paste this tag just before </body> on every page where you want chat. Replace ws_demo with your workspace ID.

HTML
<script src="https://app.chatsupporthq.com/widget.js" data-workspace="ws_demo" async></script>

That is the whole install. What the tag does:

  • It loads with async, so it never blocks your page.
  • It waits until your page has finished loading, then adds a chat button in the bottom corner.
  • The button is fixed in place, so it never moves your content. It adds no layout shift.
  • Its styles live in a shadow DOM. Your CSS cannot break the widget, and the widget cannot change your page.
  • The script is under 15 KB gzipped.

Using WordPress, Shopify or a site builder? Paste the same tag into the "custom code" or "footer scripts" setting. A WordPress plugin is Coming soon

Widget options

Set options as data- attributes on the script tag.

Script tag attributes
AttributeWhat it does
data-workspaceRequired. Your workspace ID. Without it, the widget does not load.
data-titleThe heading at the top of the chat panel. Default: Support.
data-themelight, dark or auto. Auto follows the visitor's system setting. Default: auto.
HTML, with options
<script src="https://app.chatsupporthq.com/widget.js"
  data-workspace="ws_demo"
  data-title="Help"
  data-theme="dark"
  async></script>

Control it from JavaScript

Once loaded, the widget is available as window.ChatSupportHQ. Use it to open chat from your own "Contact us" button.

JavaScript
window.ChatSupportHQ?.open();    // open the chat panel
window.ChatSupportHQ?.close();   // close it
window.ChatSupportHQ?.destroy(); // remove the widget from the page

Content Security Policy

If your site sends a Content-Security-Policy header, allow these sources:

CSP sources
script-src  https://chatsupporthq.com
connect-src https://chatsupporthq.com wss://chatsupporthq.com
style-src   'unsafe-inline'

The widget puts its styles in a <style> tag inside its shadow DOM. That is why it needs 'unsafe-inline' for styles today. It does not need it for scripts.

Keys and security

The widget needs no API key. Your workspace ID is public. It is safe in your page HTML, like a Stripe publishable key.

  • The widget sends no cookies. It keeps the open conversation ID in sessionStorage, which clears when the tab closes.
  • Requests are rate limited per visitor, so nobody can drain your plan from a script.
  • Every workspace has a hard monthly AI spend cap. When it is reached, the widget offers email contact instead of going dark.

Secret API keys for the REST API, SDKs, CLI and MCP server arrive with the public API. Coming soon When they do, keep them on your server. Never put a secret key in page HTML or in a browser app.

Your first conversation

  1. Open the page where you added the widget, and reload it.
  2. Click the chat button in the bottom corner. The panel opens with a short note that an AI is answering.
  3. Ask a question, for example "Is there a free plan?". The answer streams in word by word.
  4. Look for the numbered sources under the answer. Each one links to the page the answer came from.
  5. Click Why this answer? to open the answer receipt. See Check an answer.

The AI only answers from your content. When it has no good source, it says so and offers a person instead of guessing.

From code

You can hold the same conversation without the widget. This is the protocol the widget uses. It is stable for widget v0.1. The full public API will add versioned REST endpoints and SDKs.

first-chat.mjs (Node.js 22 or later)
const API = "https://chatsupporthq.com";
const WORKSPACE = "ws_demo";

// 1. Start a conversation.
const res = await fetch(`${API}/v1/widget/conversations`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ workspaceId: WORKSPACE }),
});
const { conversationId } = await res.json();

// 2. Connect and ask a question.
const url = `wss://chatsupporthq.com/v1/widget/conversations/${conversationId}/ws?workspace=${WORKSPACE}`;
const ws = new WebSocket(url);
ws.onopen = () => ws.send(JSON.stringify({ type: "ask", id: "q1", text: "Is there a free plan?" }));

// 3. Print the answer as it streams, then its sources.
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "delta") process.stdout.write(m.text);
  if (m.type === "done") {
    const sources = [...new Set(m.citations.map((c) => c.url))];
    console.log("\n\nSources:", sources.join(", "));
    if (m.receiptId) console.log(`Receipt: ${API}/r/${WORKSPACE}/${m.receiptId}`);
    ws.close();
  }
};

Run it with node first-chat.mjs.

Messages you receive

Server messages on the conversation WebSocket
TypeWhen
helloOn connect. Includes the AI disclosure text to show the visitor.
historyOn reconnect, with the turns so far.
deltaA piece of the answer. Append text to the turn with the same id.
doneThe answer is complete. Includes citations, receiptId and offerHuman.
statusWho is answering changed: ai, waiting, human or closed.
agentA reply from a person on the team.
errorSomething went wrong. Includes a code and a plain message.

You can send ask (a question, up to 2,000 characters), handoff (ask for a person) and feedback ({"type":"feedback","resolved":true,"turnId":"q1"}).

Check an answer

Every AI answer gets a receipt. It is a public page that shows the sources used, the model, the time, and fingerprints of the content and rules behind the answer. Share it with your team when an answer looks wrong.

Receipts are also available as JSON:

Terminal
curl https://chatsupporthq.com/v1/receipts/ws_demo/RECEIPT_ID

Talk to a person

A person is always one click away. The widget shows Talk to a person at any time, and offers it on its own when the AI is unsure.

If nobody on your team picks up soon, the widget asks for the visitor's email and question, and sends them to your inbox. It does the same when chat cannot connect or the AI is paused, so visitors are never stuck. On the demo workspace these requests are saved, but nobody reads them. Write to support@chatsupporthq.com if you need us.

Limits

  • Questions can be up to 2,000 characters.
  • Each visitor IP can start about 30 conversations or connections a minute. Past that you get 429 rate_limited.
  • Each workspace has a monthly AI spend cap, and Free plans stop at their limit instead of charging. See pricing.

Next steps