Embedding the Widget

Basic embed

Paste this snippet before the closing </body> tag:

<script src="https://widget.getchat9.live/widget.js" data-bot-id="YOUR_BOT_PUBLIC_ID"></script>
<script>
  Chat9Widget.start();
</script>

data-bot-id is your bot's public ID — safe to include in page HTML.

Loading widget.js registers window.Chat9Widget but does not mount any UI. You explicitly start the widget with Chat9Widget.start(config?) — call it with no arguments for an anonymous widget with default styling, or pass an options object to customize.

Do not add async or defer to the widget.js tag — the loader reads document.currentScript synchronously and will not register without it.

Configuration

All options are arguments to Chat9Widget.start():

<script src="https://widget.getchat9.live/widget.js" data-bot-id="YOUR_BOT_PUBLIC_ID"></script>
<script>
  Chat9Widget.start({
    mode: "bubble",          // "bubble" | "inline"
    theme: "light",          // "light" | "dark"
    color: "#7C3AED",
    position: "right",       // "right" | "left"
    target: "chat9-widget",  // inline mode only — id of the host element
    userHints: {
      name: "Anna",
      email: "anna@example.com",
      locale: "ru-RU"
    }
  });
</script>

Modes:

• Bubble — floating button, bottom corner of the page. The window has a close button in its header, and Escape closes it; the bubble hides while the window is open. On phones it opens full screen.
• Inline — renders inside a container you provide. Add <div id="chat9-widget"></div> where you want the widget. A target with a fixed height (or one stretched by flex or grid) is filled; otherwise the widget is 600px tall. The target must be displayed (not display: none) when the widget starts.

Routing from Russia

If your site primarily serves visitors in Russia, load the widget from the Russian edge proxy. Replace widget.getchat9.live with widget-ru.getchat9.live in the script src — both the widget bundle and the API origin route through it automatically:

<script src="https://widget-ru.getchat9.live/widget.js" data-bot-id="YOUR_BOT_PUBLIC_ID"></script>
<script>
  Chat9Widget.start();
</script>

This bypasses traffic throttling that some Russian ISPs apply to Vercel/Railway. Visitors outside Russia work the same way — they just hit the RU edge with a small extra hop. If you serve mixed audiences, detect the visitor's country server-side and emit a different src per request, or A/B test.

CSP

If your site uses a Content Security Policy, default origins:

script-src  https://widget.getchat9.live;
frame-src   https://widget.getchat9.live;
connect-src https://getchat9.live;

If you load the widget from the Russian edge proxy (widget-ru.getchat9.live), allow these origins instead:

script-src  https://widget-ru.getchat9.live;
frame-src   https://widget-ru.getchat9.live;
connect-src https://api-ru.getchat9.live;

Where to get the embed code

1. Log in to your Dashboard at https://getchat9.live.
2. Copy the embed block from the Install widget page.

Lifecycle API

window.Chat9Widget exposes an explicit lifecycle. The script downloads once; you control when the chat appears, when it goes away, and what identity it carries.

Session continuity

Conversation history is stored on the server. The widget keeps a session_id in the visitor's browser (localStorage) for up to 24 hours — on return visits it fetches the previous conversation from the server using that ID, so history persists across page reloads.

When userHints includes user_id or email, the storage key is scoped per visitor — different users on the same device get separate sessions.

A user_id personalizes the conversation (greeting, language, escalation details), keeps it in the same browser, restores it on another device or after localStorage is cleared, and groups the visitor's sessions in the Inbox. Without a key the ID is not verified: anyone who knows or guesses a visitor's user_id can open that visitor's conversation in the widget. Use unguessable IDs, or turn on identity verification if conversations may contain anything private. An email-only hint or an anonymous visitor (no userHints) always starts a fresh session on a new browser.

Escalating to a human agent does not end the conversation. If the visitor's email is already known, the bot goes on answering their questions normally while the ticket is open. If it is not — the default for anonymous visitors — the bot asks for an email address and keeps asking until it gets one, because support replies by email. After the handoff the bot asks whether it can help with anything else; if the visitor declines, the bot says goodbye and the chat stays open — the next message is answered as usual. There is no closed state and no "start new chat" control: a conversation only rolls over into a fresh one after a week without messages, and the previous one stays visible above a "New conversation" separator.

Greeting is shown once per browser, ever — per bot, and per identified user when you pass user_id or email. A returning visitor is not greeted again, even when a new conversation starts after a week without messages. The greeting is shown in userHints.locale if you set one, otherwise in the browser language, otherwise in English. It is not saved into the conversation, so it does not appear in the Inbox or after a page reload. Clearing browser storage or using a private window counts as a new browser, so the visitor is greeted again.

Opening the chat bubble, or loading a page with an inline widget, does not start a conversation. A conversation starts with the visitor's first message, so visitors who open the widget and never write do not create empty conversations.

Clarification: the bot may ask one follow-up question when a request is ambiguous. It appears as part of the normal text reply.

Login / logout in single-page apps

Because start, stop, and setHints are explicit, the widget can survive a full SPA login/logout cycle without reloading widget.js.

// At app startup, mount the widget anonymously:
Chat9Widget.start({ color: "#7C3AED" });
 
// Once the user logs in:
Chat9Widget.setHints({
  user_id: user.id,
  email: user.email,
  name: user.name
});
 
// User switches accounts without reloading:
Chat9Widget.setHints({ user_id: otherUser.id, email: otherUser.email });
// Conversation state resets server-side — the previous user's chat does
// not leak to the new identity.
 
// Logout — pick one:
Chat9Widget.setHints(null);   // keep the widget visible, anonymous
// or
Chat9Widget.stop();           // hide the widget completely
 
// Re-login after stop():
Chat9Widget.start({
  color: "#7C3AED",
  userHints: { user_id: user.id, email: user.email }
});

Substitute your own brand color in color (any #RGB/#RRGGBB) — or omit it for the default violet. All other options listed in Configuration are supported here too.

setHints() updates a running widget in-place — you do not need to stop and start to change identity.

For server-rendered or multi-page apps, the simplest pattern is to render the embed snippet on every page and pass the right userHints per request. On logout the page navigates and the widget is recreated naturally.

userHints

By default the widget is anonymous. Pass userHints to personalize the session — either at start() time, or later via setHints():

<script src="https://widget.getchat9.live/widget.js" data-bot-id="YOUR_BOT_PUBLIC_ID"></script>
<script>
  Chat9Widget.start({
    userHints: {
      user_id: "42",
      name: "Anna",
      email: "anna@example.com",
      locale: "ru-RU",
      plan_tier: "pro"
    }
  });
</script>

Hints are used for greeting personalization, language selection, and escalation email metadata.

Note: Hints come from the browser and can be modified by anyone. Do not use them for access control, paid-tier gating, or audit logs. Treat them as personalization suggestions only.

Fields

Escalation priority

Identity verification

Without a key, user_id is trusted as-is: anyone who knows or guesses a visitor's user_id can open that visitor's conversation. Identity verification is a stronger, optional level: Chat9 confirms that a user_id really belongs to the visitor sending it. You choose whether to use it, and it needs a server that signs.

Set up

1. In the Dashboard, go to Settings → Widget → Widget identity verification and generate a key. You can reveal/copy it later, and rotate it if it leaks — rotating invalidates the old key immediately, so any requests still signed with it stop verifying.

2. On your server (never in the browser), compute user_hash for the visitor:

   // Node.js
   const crypto = require("crypto");
    
   function userHash(userId) {
     return crypto
       .createHmac("sha256", process.env.CHAT9_WIDGET_IDENTITY_KEY)
       .update(userId)
       .digest("hex");
   }

   # Python
   import hashlib
   import hmac
   import os
    
   def user_hash(user_id: str) -> str:
       return hmac.new(
           os.environ["CHAT9_WIDGET_IDENTITY_KEY"].encode("utf-8"),
           user_id.encode("utf-8"),
           hashlib.sha256,
       ).hexdigest()

   <?php
   // PHP
   function userHash(string $userId): string {
       return hash_hmac("sha256", $userId, getenv("CHAT9_WIDGET_IDENTITY_KEY"));
   }

   // Go
   import (
       "crypto/hmac"
       "crypto/sha256"
       "encoding/hex"
       "os"
   )
    
   func userHash(userID string) string {
       mac := hmac.New(sha256.New, []byte(os.Getenv("CHAT9_WIDGET_IDENTITY_KEY")))
       mac.Write([]byte(userID))
       return hex.EncodeToString(mac.Sum(nil))
   }

   user_hash is a lowercase hex HMAC-SHA256 of the exact user_id string, using the key as the HMAC key. Compute it wherever you already render the page for a logged-in visitor, and pass it down to the client alongside user_id.

   The server trims user_id and keeps at most 200 characters before verifying — sign exactly the trimmed id you send, since a longer id won't verify.

3. Pass both in userHints, at start() or via setHints():

   <script>
     Chat9Widget.start({
       userHints: {
         user_id: "42",
         user_hash: "<computed on your server>"
       }
     });
   </script>

How it works with and without a key

• Without a key: user_id works fully. It personalizes the conversation, keeps it in the same browser, restores it across devices and after localStorage is cleared, and groups the visitor's sessions in the Inbox. The ID is not verified.
• With a key: only visitors with a valid user_hash restore conversations across devices and are grouped in the Inbox. An unsigned user_id only personalizes the conversation and keeps it in the same browser.
• A user_id that starts with hint: is always rejected and treated as absent — that prefix is reserved for the server's own synthesized IDs.
• email is never used to restore a conversation, verified or not — it's too easy to guess.
• In the dashboard Inbox, a visitor's sessions are grouped into one row by user_id; with an identity key, only for visitors with a valid user_hash.