Chat Widget

Add these two lines just before </body> on any page:

<script>window.botonomSettings = { agentKey: "wgt_live_xxx" };</script>
<script async src="https://botonom.com/widget.js"></script>

Replace wgt_live_xxx with your agent's embed key (see below). A floating launcher appears bottom-right; clicking it opens the chat panel.

You can also pass the key as a data attribute:

<script async src="https://botonom.com/widget.js" data-agent-key="wgt_live_xxx"></script>

agentKey (format wgt_live_...) is a public, rotatable identifier - not a secret. It only names which agent to load and is safe to ship in your page source. The real protection is server-side (see Security), so there is no second token to hide.

Only agents that are embed-enabled and public-facing resolve. Enable an agent and get its key from the builder below.

Set options on window.botonomSettings before the loader:

<script>
  window.botonomSettings = {
    agentKey: "wgt_live_xxx",  // required
    position: "right",          // "left" | "right"  (which bottom corner)
    mode: "compact",            // "compact" | "advanced"  (tabs + sessions)
    size: "small",              // "small" | "large"  (large = full height, 1/3 wide)
    activity: true,             // false = classic three-dot typing bubble
    theme: "light",             // "light" | "dark"
    lang:  "tr"                 // "en" | "tr"
  };
</script>
<script async src="https://botonom.com/widget.js"></script>

mode: "advanced" turns the panel into a small messenger:

• Messages tab - each visitor gets a conversation list. "New conversation" starts a fresh thread with your agent; older conversations stay listed (with the last message and time) and can be resumed anytime. Typing /new (or /yeni) inside a chat also starts a fresh conversation.
• Help tab - shows your company's Help Center articles with instant search and an article reader. The visitor can self-serve before (or instead of) messaging.

The Help tab has one requirement: install the Help Center skill on the embedded agent and publish at least one article (panel: Help Center in the sidebar). No articles or no skill = the tab simply does not appear; Messages keeps working on its own.

Articles are language-aware: tag an article with a language in the panel and it only shows when the widget runs in that language (the lang option); untagged articles show everywhere. Write the same FAQ in two languages and each visitor sees their own.

<script>
  window.botonomSettings = {
    agentKey: "wgt_live_xxx",
    mode: "advanced",
    size: "large"
  };
</script>
<script async src="https://botonom.com/widget.js"></script>

Once the loader runs, window.Botonom and window.BotonomChat are available:

window.Botonom.open();   // open the panel (e.g. from your own "Chat with us" button)
window.Botonom.close();  // close it

BotonomChat exposes the same open/close controls plus a page-trigger API:

window.BotonomChat.open();
window.BotonomChat.close();
window.BotonomChat.askAgent({
  text: "The visitor clicked help on the pricing section. Explain the plans briefly and ask one helpful follow-up question.",
  visibleUserMessage: false,
  openFirst: true,
  metadata: {
    source: "pricing-help-button",
    page: "pricing"
  }
});

<button onclick="window.Botonom.open()">Chat with us</button>

When visibleUserMessage is false, the visitor does not see the synthetic prompt. They only see the agent's real answer, and the conversation continues in the same thread.

Use BotonomChat.askAgent() for contextual buttons on your own site: pricing help, checkout help, docs help, product explainers, or any page-specific assistant action.

<button
  onclick="window.BotonomChat.askAgent({
    text: 'The visitor clicked help on the checkout page. Explain shipping, payment, and return policy briefly.',
    visibleUserMessage: false,
    openFirst: true,
    metadata: { source: 'checkout-help', page: 'checkout' }
  })"
>
  Need help?
</button>

The prompt is written by your website integration. The widget sends it to the live agent runtime, hides the prompt when requested, renders the agent reply, and keeps the thread open for follow-up questions.

Your agent's replies are not limited to text. When an agent's skills or persona produce rich content (image cards, action buttons, PDFs, links) the widget renders them natively inside the chat, with no extra setup on your side.

The agent decides when to send these; you just embed the widget.

Everything in the snippet is public, so protection is server-side, not a hidden token:

• Signed, short-lived session tokens minted server-side - the browser cannot forge one.
• Domain allowlist (coming): restrict an agent's widget to specific domains; the browser then refuses to render it elsewhere (enforced via frame-ancestors, so it cannot be spoofed).
• Rate limiting per visitor protects your token pool.
• Public scope only: embeddable agents run with the anonymous public role and cannot reach staff-only tools or escalate.

• Widget does not appear - check the agent is embed-enabled and agentKey is correct; open the console for [Botonom] warnings.
• "Widget unavailable" - the key is disabled, rotated, or the agent is not public-facing.
• Blocked by your site's CSP - allow Botonom: script-src https://botonom.com; frame-src https://botonom.com; connect-src https://ai.botonom.com wss://ai.botonom.com.