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.
<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.
| Attribute | What it does |
|---|---|
data-workspace | Required. Your workspace ID. Without it, the widget does not load. |
data-title | The heading at the top of the chat panel. Default: Support. |
data-theme | light, dark or auto. Auto follows the visitor's system setting. Default: auto. |
<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.
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:
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
- Open the page where you added the widget, and reload it.
- Click the chat button in the bottom corner. The panel opens with a short note that an AI is answering.
- Ask a question, for example "Is there a free plan?". The answer streams in word by word.
- Look for the numbered sources under the answer. Each one links to the page the answer came from.
- 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.
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.
curl can start a conversation. The answer itself streams over a WebSocket, so use the Node.js example or the widget for that part.
curl -X POST https://chatsupporthq.com/v1/widget/conversations \
-H "content-type: application/json" \
-d '{"workspaceId":"ws_demo"}'
{"conversationId":"c_Dbx46Wr4kHrpiPDSYxetDQ"}
Messages you receive
| Type | When |
|---|---|
hello | On connect. Includes the AI disclosure text to show the visitor. |
history | On reconnect, with the turns so far. |
delta | A piece of the answer. Append text to the turn with the same id. |
done | The answer is complete. Includes citations, receiptId and offerHuman. |
status | Who is answering changed: ai, waiting, human or closed. |
agent | A reply from a person on the team. |
error | Something 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:
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
- Read the pricing page, including the four billing promises.
- Publish an Agent Desk file so AI agents can reach your support desk.
- Check status.chatsupporthq.com if the widget does not load.
- Questions? Email support@chatsupporthq.com.