Chat Widget
Embed one of your agents on any website as a floating chat bubble, like Intercom or Zendesk. Two lines of script, a public embed key, and your agent is live for visitors.
This guide begins with Overview, continues through Quick start, The embed key, Configuration, and finishes with JavaScript API.
Overview
The Chat Widget puts one of your agents on any website as a floating chat bubble, the same way you would embed Intercom or Zendesk. Visitors chat with your agent directly; the conversation runs on Botonom's backend.
It is closed by default (just a launcher) and does not connect or consume tokens until a visitor opens it.
Quick start
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>
The embed key
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.
Configuration
Set options on window.botonomSettings before the loader:
<script>
window.botonomSettings = {
agentKey: "wgt_live_xxx", // required
theme: "light", // "light" | "dark"
lang: "tr" // "en" | "tr"
};
</script>
<script async src="https://botonom.com/widget.js"></script>
| Option | Type | Description |
|---|---|---|
agentKey | string | Required. The agent's public embed key. |
theme | string | light or dark. Omit for the widget default. |
lang | string | en or tr. The agent still replies in the visitor's language. |
JavaScript API
Once the loader runs, window.Botonom is available:
window.Botonom.open(); // open the panel (e.g. from your own "Chat with us" button)
window.Botonom.close(); // close it
<button onclick="window.Botonom.open()">Chat with us</button>
Rich responses
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.
| Block | What the visitor sees |
|---|---|
| Image / card | An inline image or product card |
| Buttons | Tappable quick-reply buttons |
| PDF / file | A downloadable document link |
The agent decides when to send these; you just embed the widget.
Security
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
publicrole and cannot reach staff-only tools or escalate.
Troubleshooting
- Widget does not appear - check the agent is embed-enabled and
agentKeyis 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.
Generate your snippet
Pick one of your agents to get a ready-to-paste embed snippet.
<script>window.botonomSettings = { agentKey: "wgt_live_xxx" };</script>
<script async src="https://botonom.com/widget.js"></script>