> ## Documentation Index > Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt > Use this file to discover all available pages before exploring further. # Chatbot Widget: AI Chat Bubble for Your Website > Add a customisable AI-powered chat bubble to any website with a single line of code. Route visitors to WhatsApp or your Team Inbox. The **Chatbot Widget** is a chat bubble you add to any website with a single line of code. Visitors click the bubble, chat with an AI assistant trained on your content, and can be handed off to a real agent in the [Team Inbox](/features/team-inbox) or sent straight into WhatsApp. Manage widgets under **More → Chatbot Widgets**. Each widget is fully customisable (colours, position, header, welcome message, background) and works on any website. It is protected by a long, unguessable access code rather than a login, so it runs safely on your customers' sites, not just yours. Chats started by the widget appear automatically in your Team Inbox alongside your WhatsApp conversations — there is no separate place to manage them. **Works with any setup.** The widget works no matter how your WhatsApp number is connected. AI replies come from an AI assistant you set up under [AI Training](/features/ai-training); the "open WhatsApp" option simply opens a chat with your number, and an agent reply from the inbox is sent back through your connected WhatsApp. ## Widget Modes A widget runs in one of three modes: Image | Mode | Behaviour | Requires | | ------------ | --------------------------------------------------------------------------------------------- | ----------------------------------- | | **AI** | Visitor chats with the AI assistant right inside the bubble; the whole conversation is saved. | An active AI assistant selected. | | **WhatsApp** | The bubble opens a WhatsApp chat with your number, optionally with a pre-filled message. | A target WhatsApp number. | | **Both** | The AI answers in the bubble, with a button to continue on WhatsApp. | An assistant *and* a target number. | **AI modes require an assistant.** If you pick *AI* or *Both* you must choose an AI assistant from your workspace, otherwise the widget won't save. Create one under [AI Training](/features/ai-training) first, then attach it here. ## Create a Widget Go to **Chatbot Widgets** and click **Create Widget**. Give it a **name** and choose a **mode** (AI / WhatsApp / Both). For AI modes, pick the **AI assistant**. For WhatsApp modes, set the **target number** (country code + number) and an optional **prefilled message**. Customise the bubble, header, message bubbles, action button, and background (see [Appearance](#appearance--behaviour) below). Enable pre-chat fields to collect **name**, **email**, and/or **phone** before the chat starts. Restrict which websites can load the widget (see [Embed & allowed domains](#embed--allowed-domains)). Click **Save**. On the first save Soneka creates the widget's access code and gives you the **embed code** to paste on your site, plus a live **preview link**. ## Appearance & Behaviour | Setting | Controls | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Position** | Bubble corner — bottom-right or bottom-left. | | **Button colour / image** | The floating bubble's colour, or a custom icon image (falls back to a built-in chat icon). | | **Header** | Header title, background colour, and text colour. | | **Welcome message** | The first message shown when the panel opens. It is also seeded into the conversation so agents see it as the opening bubble in the inbox. | | **Message bubbles** | Bubble colour and text colour for chat messages. | | **Body background** | Solid colour or a background image. | | **Action button** | Label, background, and text colour for the primary call-to-action button (used for the WhatsApp handoff in WhatsApp/Both modes). | | **Pre-chat fields** | Whether to collect name / email / phone before the chat starts. | | **Auto-open** | Whether the panel opens automatically a moment after page load. | ## Link an AI Assistant * **Where it comes from.** AI replies are generated by an AI assistant you create and train under [AI Training](/features/ai-training) (on your docs, FAQs, and web pages). The widget only lets you pick **active** assistants from your workspace. * **How replies flow.** When a visitor sends a message, Soneka saves it, asks your assistant for a reply, saves that too, and shows it in the bubble. If the assistant runs into a problem, the visitor sees your assistant's fallback message (or a generic "a team member will follow up" line) instead of a broken chat. * **Switching modes.** Move a widget from AI to Both to add a "continue on WhatsApp" button alongside the AI chat, or to WhatsApp-only to skip the in-bubble AI entirely. ## Embed & Allowed Domains After saving, copy the one-line code and paste it **just before the closing `` tag** of any page you want the widget on. It adds the floating button, and when a visitor clicks it, the chat panel opens. Agent replies from your inbox appear in the panel automatically, without the visitor needing to refresh. ```html theme={null} ``` **Where to paste it:** * **WordPress:** a "before ``" snippet plugin or your theme footer. * **Shopify:** your theme's main layout file, before ``. * **Plain HTML:** at the end of every page (or in a shared footer include). One snippet per site is enough — it loads on every page. ### Allowed domains The widget runs inside your customer's website. The **allowed-domains** list controls which websites are permitted to load it: * **Empty list (default)** → the widget runs on *any* site. The access code is the gate, and rate limiting guards against abuse. * **Non-empty list** → only the listed websites are allowed; everything else is blocked with a clear message in the browser's developer console telling you which domain to add. * **Format.** Enter plain domain names like `acme.com` or `shop.acme.com` — any `https://` prefix and path are removed for you, capitalisation doesn't matter, and duplicates are ignored. You can add up to **50 domains**. * **No wildcards.** You can't use `*.acme.com` to cover all subdomains — add each domain explicitly, so a lookalike like `evil.acme.com` can never sneak in. When a website is allowed, the visitor's chat stays connected to the same conversation as they move between pages. Leave the list empty while you set up, then lock it down to your real websites once you know them. ## AI Replies & Team Inbox Handoff * **In-bubble AI.** In AI / Both mode the assistant answers directly in the bubble, and both sides of the conversation are saved. * **Handoff to WhatsApp.** In WhatsApp / Both mode the button opens a WhatsApp chat with your number (with the pre-filled message, if set). The visitor continues with your team in the [Team Inbox](/features/team-inbox), where it behaves like any other WhatsApp conversation (assignment, notes, response targets). * **Agent takeover.** Widget conversations appear in your inbox like any other chat, so an agent can step in and reply at any time; the visitor sees the agent's message without refreshing. * **Visitor capture.** If you enabled pre-chat fields, the visitor's name, email, and phone are recorded and shown to the agent as context, so they have background immediately. ## Visitor Tracking & Rate Limits * **Returning visitors.** The widget remembers a visitor (using a cookie tied to that one widget) so when they come back, the inbox shows one continuous conversation rather than a new one each visit. A cookie from one widget can never be used to read another widget's conversations. * **What's recorded.** For each visitor: a unique ID, any captured name/email/phone, the page they came from, their browser, their IP address, and when they were first and last seen. * **Stats.** The widgets list shows a visitor count per widget plus a workspace-wide total, alongside how many widgets are active. * **Rate limits.** To prevent abuse if your embed code is copied, each visitor is limited to **60 messages per minute**, and the chat checks for new replies up to **120 times per minute**. Normal chats stay well under these. ## Manage Widgets * **Reset access code:** if your embed code is copied or ends up on the wrong website, reset the access code — the old code stops working immediately and you re-paste the new one. Saved conversations are unaffected. * **Duplicate:** makes a copy of a widget with a fresh access code so you can run a variant on another site. * **Pause:** a paused widget stops loading on sites until you reactivate it. * **Delete:** removes the widget. **Keep your access code safe.** It is visible in your site's page source. Use the allowed-domains list for sensitive sites, and reset the code if you suspect misuse. ## Troubleshooting | Symptom | Likely cause & fix | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bubble doesn't appear on the site | The embed code must be present before ``, the widget must be **active**, and the access code must be the current one (resetting it makes old codes stop working). A paused or deleted widget won't load. | | Widget blocked / error in the browser console | The website isn't on the widget's allowed-domains list. Add the domain (e.g. `shop.acme.com`), or empty the list to allow any site. | | Save rejected — "AI mode needs an assistant" | You chose AI or Both without selecting an assistant. Create one in AI Training and pick it, or switch to WhatsApp mode. | | Save rejected — "Assistant not in this workspace" | The selected assistant belongs to another workspace. Pick one from your current workspace. | | AI gives a fallback message every time | The assistant is hitting an error or has no fallback set. Check its training and settings under [AI Training](/features/ai-training). | | "Open WhatsApp" button missing | WhatsApp/Both mode needs a valid target number (country code + number). Set it and save. | | New conversation created on every visit | The visitor's browser is blocking the cookie that remembers them. The widget still works; conversations just won't link across visits. | | Visitors hitting limits during a busy chat | Each visitor can send up to 60 messages a minute — normal use stays well under this. |