Embedding the Widget

Basic embed

Copy the snippet from the Dashboard and paste it before the closing </body> tag. It loads a small script from your API host and points the iframe UI at the Chat9 app.

Example (placeholders — the Dashboard fills in your real bot public ID and URLs):

<script>window.Chat9Config={widgetUrl:"https://getchat9.live"};</script>
<script
  src="https://ai-chatbot-production-6531.up.railway.app/embed.js"
  data-bot-id="YOUR_BOT_PUBLIC_ID">
</script>

data-bot-id carries your bot's public_id, not the secret API key. It is safe to ship in page HTML.

You can choose between two modes on the Embed page:

• Bubble (default) — floating chat button in the bottom-right corner.
• Inline — renders the widget inside an existing container on your page. Add data-mode="inline" and data-target="<elementId>", and put an empty <div id="<elementId>"></div> where you want the widget.

What the widget does

• A floating chat iframe appears in the bottom-right corner of your page (about 400×600px).
• Users type questions and receive answers from your documentation.
• Session continuity works across messages in the same visit.
• If the widget starts a brand-new empty conversation, it can show a default greeting instead of an error or blank state.
• If the bot needs one missing detail, it can ask a single follow-up question (embedded in the same text reply) instead of guessing.
• The widget works in any language.

Language behavior — short version: the bot replies in the language of the user's question once they've typed one; before that, it uses your KYC locale if provided, then the browser locale, then English. See Language Support for the full contract, including sticky retention and the dashboard escalation-language override.

Where to get the embed code

1. Log in to your Dashboard at https://getchat9.live.
2. Copy the embed block from the Dashboard home (/dashboard). The widget loads your bot's public_id from the data-bot-id attribute on the script tag.

CORS

The widget is designed to work on arbitrary sites because the public loader injects an iframe hosted by Chat9. You do not need to expose your private API key in page HTML.

Session continuity

The widget keeps a session_id so the bot can maintain context across follow-up questions.

Current behavior:

• anonymous sessions are stored in the browser and can continue in the same browser for up to 24 hours
• identified sessions can also be resumed by Chat9 on POST /widget/session/init for the same user_id if the previous chat is still open and was active within 24 hours
• closed chats are not resumed

If a chat is explicitly closed by support/escalation flow, the widget shows Start new chat. The old transcript stays visible, the widget marks the next section as a new conversation, and the next message starts a fresh session below the old history.

Greeting behavior:

• when the widget opens a brand-new session with no resumed transcript, it can show the default greeting automatically
• if an existing session is resumed from the last 24 hours, the greeting is not shown again
• after Start new chat, the next fresh empty session shows the greeting again

Clarification behavior:

• Chat9 may ask one clarification question when the user's request is ambiguous or missing a critical parameter, but at most one blocking clarifying question per conversation.
• The clarifying question is part of the assistant's normal text reply — there is no separate structured payload and no quick-reply buttons.
• Clarification replies are treated as part of the same conversation context, not as a brand-new standalone question.
• Empty follow-up turns after the conversation has already started are still rejected as invalid input.

Security

The bot public_id in the data-bot-id attribute identifies which bot to load; it is intended to appear in page HTML. Keep your signing secret (used to generate identity tokens server-side) and your API key (for dashboard/API use) secret — do not expose them in client-side code or commit them to public repos.

Identified sessions (optional)

By default the standard widget embed is anonymous. Chat9 knows which bot should answer, but does not know who the end user is.

Identified sessions are an advanced integration path that lets you attach verified user context to a widget session.

How it works

1. In Dashboard → Settings → Widget API, generate a signing secret.
2. Store that secret on your server — never in client-side code.
3. Your server generates a short-lived signed identity_token for each logged-in user.
4. Your page sets window.Chat9Config.identityToken before the embed script loads. For anonymous visitors, set it to null.
5. The widget calls POST /widget/session/init with bot_id + identity_token.
6. Chat9 validates the token and returns session_id + mode (identified or anonymous).
7. All subsequent POST /widget/chat requests use that session_id.

The token is HMAC-signed. Any tampering is detected. The payload is encoded, not encrypted — do not put passwords, card data, or other secrets inside it.

If the same identified user returns later, Chat9 may resume the previous chat if it is still open and was active within the last 24 hours.

Step 1 — Get a signing secret

Go to Dashboard → Settings → Widget API and click Generate secret. Copy the value and store it in your server environment (e.g. CHAT9_SIGNING_SECRET). Never expose it in client-side code or commit it to a repository.

Step 2 — Generate a token server-side

const crypto = require("crypto");
 
function makeWidgetIdentityToken({
  secret,
  userId,
  extras = {},
  ttlSeconds = 300,
}) {
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    user_id: userId,
    exp: now + ttlSeconds,
    iat: now,
    ...extras,
  };
 
  const sorted = {};
  for (const key of Object.keys(payload).sort()) {
    sorted[key] = payload[key];
  }
 
  const json = JSON.stringify(sorted);
  const b64 = Buffer.from(json, "utf8")
    .toString("base64")
    .replace(/[+]/g, "-")
    .replace(/[/]/g, "_")
    .replace(/=+$/, "");
 
  const sig = crypto
    .createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(b64)
    .digest("hex");
 
  return `${b64}.${sig}`;
}

Required payload fields:

• user_id — any non-empty string
• exp — expiry time, Unix timestamp in seconds
• iat — issued-at time, Unix timestamp in seconds

Optional payload fields currently supported by Chat9:

• email
• name
• plan_tier
• audience_tag
• company
• locale

Example payload:

{
  "user_id": "cust_12345",
  "email": "user@example.com",
  "plan_tier": "growth",
  "audience_tag": "b2b",
  "locale": "en-US",
  "exp": 1775399700,
  "iat": 1775399400
}

Step 3 — Pass the token to the embed script

In your server-rendered page template, inject the token before the embed script:

<!-- Server renders the token for logged-in users, null for anonymous -->
<script>
  window.Chat9Config = {
    widgetUrl: "https://getchat9.live",
    identityToken: "{{ identity_token_or_null }}"
  };
</script>
<script src="https://YOUR_API_HOST/embed.js" data-bot-id="YOUR_BOT_PUBLIC_ID"></script>

The widget automatically calls POST /widget/session/init with your bot_id and identity_token. No private API key is ever sent from the browser.

The token is delivered to the widget iframe over an internal postMessage handshake — never via URL parameters — so signed tokens never appear in browser history, server access logs, or Referer headers. You don't need to do anything for this; it's how embed.js and the hosted widget talk to each other.

If you prefer to call session/init directly (e.g. from a custom integration without embed.js):

curl -X POST "https://YOUR_API_HOST/widget/session/init" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "YOUR_BOT_PUBLIC_ID",
    "identity_token": "YOUR_SIGNED_TOKEN",
    "locale": "en-US"
  }'

Successful response:

{
  "session_id": "1c576fd8-cf10-4b58-a4e7-460ea0d19dbe",
  "mode": "identified"
}

If the token is missing or invalid, Chat9 still returns a session but with:

{
  "session_id": "1c576fd8-cf10-4b58-a4e7-460ea0d19dbe",
  "mode": "anonymous"
}

Step 4 — Send chat messages with the returned session

Use the session_id from session/init in later chat requests:

curl -X POST "https://YOUR_API_HOST/widget/chat?bot_id=YOUR_BOT_PUBLIC_ID&session_id=1c576fd8-cf10-4b58-a4e7-460ea0d19dbe" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

Public widget responses may include:

• a normal answer derived from your knowledge base
• the default localized greeting when a new empty conversation starts
• a partial answer with a caveat when the bot is only partially confident
• a single clarifying question (embedded in the same text reply) when the bot needs one missing detail to answer reliably
• an escalation handoff message when the bot cannot answer safely

The reply is a JSON object whose message content lives in a single text field (alongside session_id, chat_ended and an optional ticket_number). There is no structured clarification payload and the widget does not render quick-reply buttons.

Token field reference

What mode means

plan_tier and escalation priority

When the bot escalates a conversation to a human, Chat9 uses plan_tier from the token to set the ticket priority:

Pass plan_tier in the identity token to make sure premium users' escalation tickets surface first in your Escalations inbox.

What Chat9 uses from KYC

Stored in chat context:

• user_id
• email
• name
• plan_tier
• audience_tag
• company
• locale

Used in the LLM prompt:

• plan_tier
• locale
• audience_tag

Used for richer escalation metadata:

• user_id
• email
• name
• plan_tier

Security checklist

• Generate the token on your server, never in browser JavaScript
• Store the signing secret in an environment variable, not in source code
• Use a short TTL (300 s is a reasonable default)
• Rotate the secret from the Dashboard if it is ever exposed
• Treat invalid tokens as a fallback to anonymous mode, not as a widget outage
• Do NOT put passwords, card numbers, or other secrets in the token payload