Website widget
Embed an AKOBOT agent on any website with a lightweight script. Visitors get a chat bubble; on first open the widget bootstraps a secure session and loads the agent chat frame.
Audience — Site owners, marketers, and developers who want to add an AKOBOT agent to a public site or app without rebuilding the chat UI.
In this article
- What the widget is and where it works
- Installation steps from download to verification
- HTML, Next.js, React, and WordPress examples
- Configuration, customization, troubleshooting, and FAQ
1. Overview
The AKOBOT Widget is a production embed script that adds a floating chat bubble to your site. When a visitor opens it, the script calls POST /api/widget/{agentId}/bootstrap to obtain a short-lived session token, then loads the agent chat inside an iframe.
Supported websites and frameworks
Any site that can load a JavaScript file works. Common setups include static HTML, WordPress, Webflow, Shopify (theme scripts), Next.js, React, Vue, and other SPA frameworks that mount a script after hydration.
| Platform | Integration approach |
|---|---|
| HTML / static sites | Script tags before </body> |
| Next.js / React | Client component that injects the script once |
| WordPress | Theme footer or wp_enqueue_script |
| Other CMS / builders | Custom code / footer script block |
Key features
- Pre-configured download from the Agent Store embed dialog, or hosted CDN script.
- Domain allowlisting so only approved origins can bootstrap sessions.
- Configurable position, size, and open/close callbacks.
- Mobile-friendly full-screen chat on small viewports.
- Lazy session bootstrap — the chat frame loads on first open, not on every page view.
Start from the dashboard
2. Installation steps
Whitelist your domain first
example.com) to the agent's allowed domains in the dashboard. Without this, bootstrap fails and the widget shows an error.Step 1 — Download embed.js
In the Widget Embed dialog, download the pre-configured file. It is named like akobot-widget-YOUR_AGENT_ID.js and already includes your agent ID and API base.
Alternatively, skip the download and use the hosted script at https://api.akobot.ai/widget/embed.js with a window.AkobotWidget config block (see Manual Setup in the dialog).
Step 2 — Upload to your website server
Upload the downloaded file to a public path on your server, for example /js/akobot-widget.js. Ensure the URL returns JavaScript with a 200 status and is not blocked by your CDN or firewall.
Step 3 — Add the script before the closing body tag
Include the script just before </body> so the rest of the page renders first.
Loading…
Step 4 — Verify the widget loads
- Open your site in a normal browser window (not a sandboxed preview that blocks third-party scripts).
- Confirm the chat bubble appears in the corner.
- Click the bubble — the loading spinner should resolve into the agent chat.
- If something fails, open DevTools → Console / Network and check the troubleshooting section below.
3. HTML integration example
Recommended pattern for the hosted embed: set window.AkobotWidget before loading embed.js.
Loading…
Full page example
Loading…
4. Framework guides
HTML
Use the snippets in the previous section. Prefer placing the tags at the end of body so layout and critical CSS are not delayed.
Next.js
Load the widget only on the client. A small client component keeps the App Router happy and cleans up on unmount during development navigation.
Loading…
React
Same idea outside Next.js — inject once in useEffect.
Loading…
WordPress
Add the snippet to your theme footer, or enqueue scripts properly so caching plugins and concatenation tools still load config before the embed.
Loading…
5. Configuration
Configuration is read from window.AkobotWidget when the hosted embed.js loads. The downloadable pre-configured file bakes the same values into a local CONFIG object.
| Option | Required | Description |
|---|---|---|
agentId | Yes | Unique ID of the agent to embed. Copy it from the Widget Embed dialog footer. |
apiBase | No | Base URL for widget APIs and the frame (default https://api.akobot.ai). Use your environment URL when testing against staging. |
position | No | Bubble placement: bottom-right (default) or bottom-left. |
| Theme | — | The chat frame follows the widget shell theme (light/dark) managed inside the framed experience. The public embed script does not expose a theme string on window.AkobotWidget today. |
| Auto open | — | Not supported by the current embed script. The bubble stays closed until the visitor clicks it (or Escape / backdrop closes an open panel). |
| Allowed domain | Dashboard | Configured per agent as whitelisted / allowed domains. The browser origin that hosts the script must match an entry or bootstrap is rejected. |
Widget URL
{apiBase}/widget/embed.js. Chat frame (loaded after bootstrap): {apiBase}/widget/frame/{agentId}#widget_token=…. You do not need to construct the frame URL yourself.6. Customization
All public options on the hosted embed:
Loading…
| Option | Default | Notes |
|---|---|---|
width | 480px | Desktop chat panel width. On viewports ≤480px the panel goes full screen. |
height | 720px | Desktop chat panel height. |
onOpen | — | Optional callback when the panel opens. |
onClose | — | Optional callback when the panel closes. |
Deeper visual changes
embed.js from the dialog if you need to adjust bubble styles, z-index, or other CSS in the injected stylesheet. Keep agentId and bootstrap URL logic intact.7. Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| Widget not loading / no bubble | Script missing, blocked, or wrong path | Confirm the script URL returns 200. Check that the tag is in the live HTML (view source). Disable ad blockers for a quick test. |
| Script blocked | CSP, security plugins, or mixed content | Allow script-src for your API host. Serve the page over HTTPS when loading the HTTPS embed. WordPress security plugins may need an allowlist entry. |
| Invalid Agent ID | Wrong or empty agentId | Console shows [AkobotWidget] agentId required. Copy the ID from the Widget Embed dialog footer and set it before the script loads. |
| CORS / bootstrap network errors | Origin not allowlisted or API unreachable | Add the exact hostname (and www variant if used) to allowed domains. Inspect the bootstrap POST in Network — status and response message explain most failures. |
| Console errors after open | Bootstrap failed or frame blocked | Look for [AkobotWidget] Bootstrap failed. Ensure third-party cookies/storage are not required for your case (bootstrap uses credentials: "omit"). Confirm iframes are not forbidden by X-Frame-Options / CSP on the API host (AKOBOT serves the frame for this purpose). |
8. FAQ
Do I need an account on the visitor’s browser?
No. End users chat as widget guests. Your team manages the agent, domains, and billing inside the AKOBOT dashboard.
Can I embed multiple agents on one page?
The current embed assumes a single window.AkobotWidget config and one bubble container. Use one agent per page, or host separate pages/sections each with its own embed.
Download vs hosted script — which should I use?
Download is simplest for static sites and keeps a pinned copy under your control. Hosted embed.js is better when you want platform updates automatically and are comfortable setting config inline.
Does the widget affect Core Web Vitals?
Impact is usually small if you load the script at the end of body. The chat iframe and session bootstrap run only after the first open, which keeps initial page work lighter.
Where do I manage allowed domains?
In the agent settings / Widget domain section of the Agent Store, or from the same flow that opens the Widget Embed dialog.
9. Best practices
Performance
- Place the script before the closing body tag; avoid putting it in the document head.
- Do not load the widget inside every micro-frontend mount if the bubble should appear once globally.
- Prefer one embed per page to avoid duplicate bubbles and competing z-index stacks.
Security
- Keep the allowed-domains list tight — production and staging hostnames only.
- Never put private API keys in the public embed snippet; the widget uses bootstrap tokens instead.
- Review agent instructions and tools before embedding on a public marketing site.
Caching and deployment
- If you self-host a downloaded file, bust caches when you regenerate it (new query string or filename).
- After changing allowed domains, hard-refresh the site and retry bootstrap — CDN HTML caches can serve an old test page that still points at the wrong host.
- Validate on production hostname, not only localhost, before go-live.
Related