# Install the widget

> Deploy an agent to your website with the five-step web deploy wizard, paste one script tag, allow your domains, and fix a widget that doesn't appear.

Source: https://docs.amomic.in/channels/web-chat

---

The web widget puts one of your agents on your website as a chat window. You set it up per agent, with the **Deploy to the web** wizard, and install it by pasting one script tag. There is no package to install and nothing to keep up to date: the script is served by Amomic-AI and the widget reads its configuration every time it loads.

**Who can do it:** owners and admins. A member who opens the wizard sees *"Only an owner or admin can deploy"* and a link back to the agent's deployments. The web widget is included on every plan, Free included.

![The Install step of Deploy to the web: Allowed websites lists veloriahome.in, www.veloriahome.in and support.veloriahome.in, Shopify is selected, and the snippet is shown in a theme.liquid editor tab. The live preview of the widget is on the right.](https://docs.amomic.in/screens/webchat/deploy-install.light.webp)

*The Install step. The live preview on the right is the real widget, running against your agent.*

## Before you begin

- **Publish the agent at least once.** The wizard needs a published version. Without one it shows *"Publish the agent first"* with a **Go to versions** button.
- **Know which sites the widget will run on.** You list them in the Install step, and the widget refuses to load anywhere else.

```html title="The tag you will paste"
<script async src="https://services.amomic.in/widget.js" data-bot="wgt_01JA7X4M9Q2T6W1Y5R8N3K0PVA"></script>
```

Your `data-bot` value is your widget's own id. It always starts with `wgt_` and it isn't a secret.

## Deploy an agent to the web

::: steps

::: step Open the wizard
Go to **Agents**, open the agent, click **Deploy** and choose **Web widget**. You can also use **Deploy here** on the Web widget card of the agent's **Deployments** tab.

If the agent already has a live web deployment, the menu item reads **Manage Web deployment** and opens the **Deployments** tab. Click **Edit settings** on the web deployment to reopen the wizard.
:::

::: step Website
Enter your **Website address**, for example `https://veloriahome.in`, and click **Continue**. Your website is always an allowed site for the widget. In the background, the console reads your homepage for its brand colour and font and pre-fills the next steps with them.
:::

::: step Knowledge
Check the knowledge bases the agent answers from. Each shows whether it is **ready**. Attach another with **Attach another knowledge base…**, or detach one with the unlink icon. **Manage knowledge in the agent studio** opens the agent's **Knowledge** tab.

Attaching and detaching here changes the agent itself, on every channel it serves, as soon as you do it.

![The Knowledge step listing Product manuals, Warranty & service policy and Website FAQ, each marked ready](https://docs.amomic.in/screens/webchat/deploy-knowledge.light.webp)

*The Knowledge step: the knowledge bases the agent answers from.*
:::

::: step Identity
Set the bot name, company name, welcome message, suggested questions and profile picture. See [Customise the widget](/channels/web-chat-config#identity).
:::

::: step Appearance
Set the brand colour, font, theme, position and launcher button, plus the greeting bubble, **Remember conversations**, restart and the lead form. See [Customise the widget](/channels/web-chat-config#appearance) and [Capture leads](/channels/web-chat-leads).
:::

::: step Install
List your **Allowed websites**, pick your platform, copy the snippet and click **Set live**. On a widget that is already live, the button reads **Save changes** and the footer shows **This bot is live**.
:::

:::

The steps are clickable, so you can jump back to any of them. The **Live preview** on the right is your actual widget, answering from your agent, and it updates as you edit.

![The wizard after Save changes: Veloria Support is live! with a Web · Live badge, the script tag to copy, a Custom UI box with the headless snippet, and a Done button](https://docs.amomic.in/screens/webchat/deploy-live.light.webp)

*After Set live or Save changes, the snippet to paste and the custom UI snippet.*

When you click **Set live**, Amomic-AI creates your workspace's web connection (the first time), creates a deployment of the agent's published version, checks it, and activates it. You land on *"{name} is live!"* with the snippet to copy. **Done** takes you to the agent's **Deployments** tab.

### When your changes reach visitors

Not every step saves at the same moment. On a widget that is already live:

| What you change | When visitors get it |
|---|---|
| Website, and everything on **Identity** | When you click **Continue** on that step. |
| Brand colour, font, theme, position, launcher | When you click **Continue** on **Appearance**. |
| Greeting bubble, **Remember conversations**, restart, lead form, **Allowed websites** | When you click **Save changes** (or **Set live**) on **Install**. Leave the wizard before that and these changes are lost. |
| Knowledge attached or detached | Immediately. |
| The agent's instructions, tools and knowledge, edited in the agent studio | As soon as they are saved there. Test risky changes in the agent's test chat first. See [Agents](/build/agents). |

Visitors see the new look on their next page load.

::: warning Check the brand colour each time you reopen the wizard
Every time you open the wizard, it re-reads your website and pre-fills **Brand color** and **Font** with what it finds there. If you had chosen a different colour, check **Appearance** before you click **Continue** or **Save changes**, or the website's colour replaces yours.
:::

## Pick your platform

The tag is the same everywhere. The Install step's **What's your website built with?** picker tells you where each platform wants it, and shows the file name you are pasting into.

| Platform | Where to paste | File shown |
|---|---|---|
| **HTML / other** | Just before the closing `</body>` tag of every page. | `index.html` |
| **Next.js** | Once, in `app/layout.tsx` (App Router) or `pages/_app.tsx`, with `next/script`. | `app/layout.tsx` |
| **React (Vite/CRA)** | Before `</body>` in `index.html` (Vite) or `public/index.html` (CRA). | `index.html` |
| **Vue** | Before `</body>` in `index.html`. | `index.html` |
| **Nuxt** | In `nuxt.config.ts` under `app.head.script`, or in `app.html`. | `nuxt.config.ts` |
| **Angular** | Before `</body>` in `src/index.html`. | `src/index.html` |
| **Svelte / SvelteKit** | Before `</body>` in `src/app.html` (SvelteKit) or `index.html` (Vite). | `src/app.html` |
| **WordPress** | A header/footer plugin (for example WPCode), in the footer. Or in `footer.php`, before `</body>`. | `footer.php` |
| **Shopify** | Online Store → Themes → Edit code → `theme.liquid`, before `</body>`. | `theme.liquid` |
| **Wix** | Settings → Custom Code → Add Custom Code. Apply to All pages, load once, place in Body — end. | `custom-code.html` |
| **Squarespace** | Settings → Advanced → Code Injection, in the Footer box. | `code-injection.html` |
| **Webflow** | Project Settings → Custom Code, in Footer Code. Then publish. | `footer-code.html` |
| **Framer** | Site Settings → General → Custom Code, in "End of `<body>` tag". Then publish. | `custom-code.html` |
| **Google Tag Manager** | New Tag → Custom HTML. Trigger on All Pages, then publish the container. | `tag.html` |

Next.js and Nuxt get their own code, and a **Prefer plain HTML?** box with the universal tag underneath.

::: codegroup

```jsx Next.js
// app/layout.tsx — inside your root layout's <body>
import Script from "next/script";

<Script src="https://services.amomic.in/widget.js" data-bot="wgt_01JA7X4M9Q2T6W1Y5R8N3K0PVA" strategy="lazyOnload" />
```

```javascript Nuxt
// nuxt.config.ts
app: {
  head: {
    script: [{ src: "https://services.amomic.in/widget.js", async: true, "data-bot": "wgt_01JA7X4M9Q2T6W1Y5R8N3K0PVA" }],
  },
},
```

:::

Two details apply on every platform:

- **Keep `async`** (or `strategy="lazyOnload"` in Next.js). The widget loads after your page, which is the right trade for a support widget.
- **Include it once per page**, in a layout or footer that renders once. Only the first widget tag on a page loads. Any later one is ignored, even if it points at a different widget, so one page can show one widget.

If `data-bot` is missing or empty, the script does nothing at all: no launcher and no error.

## Allow your domains

**Allowed websites** in the Install step lists the sites the widget may run on, one per line or comma-separated. Your website address is always allowed. If you leave the list empty, **Set live** uses your website's domain; with neither, it stops with *"Add at least one allowed domain (or your website) before going live."*

The matching rules:

| Rule | Example |
|---|---|
| **Hostnames only.** Scheme, port and path are ignored. | Enter `veloriahome.in`, not `https://veloriahome.in/support`. |
| **`www.` doesn't matter.** | `veloriahome.in` covers `www.veloriahome.in`, and the other way round. |
| **A domain covers its subdomains.** | `veloriahome.in` covers `support.veloriahome.in` and `shop.eu.veloriahome.in`. |
| **No wildcards.** An entry containing `*` is ignored. | Enter `veloriahome.in`, not `*.veloriahome.in`. |
| **Up to 20 entries.** | List parent domains rather than every subdomain. |
| **`localhost` is always allowed.** | `http://localhost:3000` works without being listed. `127.0.0.1` is a different hostname: add it if you develop on it. |

::: warning Being allowed is not the same as being live
The domain check is only half of it. The widget also has to be live. A widget whose web deployment is disabled, or that has never been set live, refuses to load on every site, `localhost` included. Only the console's live preview works on a draft.
:::

To put the same widget on more sites, add them to **Allowed websites** and click **Save changes**. You don't need a second deployment.

## What visitors see

When everything is in order, the launcher appears in the corner you chose, a moment after your page loads. If you turned on the greeting bubble, it appears beside the launcher about two and a half seconds later.

![The closed widget: a round teal launcher with a headset icon and, beside it, the greeting bubble 'AC making noise? Ask us' with a dismiss button](https://docs.amomic.in/screens/webchat/widget-greeting.light.webp)

*The closed widget with its greeting bubble.*

### When the widget refuses to load

If the widget is refused, **no launcher appears at all**. Visitors see your page as if the tag weren't there. The browser's developer console shows why:

```text
[Amomic-AI widget] failed to load: This widget is not enabled for this website.
```

| Message after `failed to load:` | Why | Fix |
|---|---|---|
| *This widget is not enabled for this website.* | The page's hostname isn't your website and isn't in **Allowed websites**. | Add the domain and click **Save changes**. Check for a subdomain of another domain, an entry with `*`, or `127.0.0.1`. |
| *This chatbot isn't live yet.* | The domain is allowed, but the widget isn't live: it was never set live, or its deployment was disabled. | Click **Set live** in the wizard, or **Enable** the web deployment on the agent's **Deployments** tab. |
| *Unknown widget.* | The `data-bot` id doesn't match any widget. | Copy the snippet again from the Install step. |

The live preview in the console skips the live check on purpose, so you can build against a draft. That is why something can work in the preview and not on your site.

### When your workspace is out of allowance

A visitor who starts a new conversation while your workspace has used up its plan allowance gets this reply instead of an answer:

> Sorry — the assistant isn't available right now. Please reach out to the team directly and they'll be happy to help.

Conversations already in progress carry on. See [Credits](/operate/credits#what-happens-when-you-run-out).

Visitors see the same reply while your workspace is **suspended** for an unpaid plan invoice, and then it applies to conversations already in progress too. Visitors are never told why. It lifts by itself once the invoice is paid. See [When a payment fails](/operate/plan-changes#when-a-payment-fails).

## Opening and closing it from your own UI

The widget exposes two methods on the page:

```javascript
window.AmomicWidget.open();
window.AmomicWidget.close();
```

Use them to wire your own triggers, such as a "Chat with us" link in your header:

```html
<button type="button" onclick="window.AmomicWidget && window.AmomicWidget.open()">
  Chat with us
</button>
```

`window.AmomicWidget` exists once the script has loaded and the widget has mounted. Because the tag is `async`, guard calls made early in the page's life, as above.

There is nothing else on the object: no events, no way to send or prefill a message. For programmatic messages and streaming, use the [custom UI client](/channels/web-chat-custom-ui).

## What the visitor's browser stores

No cookies, and no message text. The widget keeps a few opaque ids in the visitor's `localStorage`:

| Key | Holds |
|---|---|
| `amomic_vid` | An anonymous visitor id for your site, shared with the [custom UI client](/channels/web-chat-custom-ui) if you use it too. |
| `amomic_cid_<widget id>` | The current conversation's id for this widget. |
| `amomic_lead_<widget id>` | Whether the visitor submitted (`1`) or skipped (`skipped`) the [lead form](/channels/web-chat-leads). |
| `amomic_greet_<widget id>` | Set once the visitor dismisses the greeting bubble. |

The transcript itself is kept by Amomic-AI. On each page load, the widget asks for it and shows it again, as long as **Remember conversations** is on and the last message is within the **Remember for** window (7 days by default). See [Remember conversations](/channels/web-chat-config#remember-conversations).

Consequences:

- **A refresh or return visit restores the chat** when Remember conversations is on and the window hasn't passed.
- **Clearing site data starts over:** new visitor, new conversation, and the lead form is asked again.
- **A private window is a new visitor each time.**

The widget renders inside an isolated shadow root, so your site's CSS can't reach it and its styles can't leak into your page.

## Rate limit

**12 requests per 60 seconds, per visitor, per widget**, counting messages, images and lead-form submissions. New sessions are limited to 30 per minute per IP, and all visitor traffic to 60 per minute per IP. Loading the script isn't counted.

A visitor over the limit sees **Not sent** with a **Retry** control under their own message. The window slides, so a few seconds later **Retry** goes through. Real visitors almost never hit this; testing in quick succession does.

## Troubleshooting

::: details The widget doesn't appear at all
Work through it in order:

1. **Open the browser console** on the live page and look for `[Amomic-AI widget] failed to load:`. The message tells you which fix applies (see [When the widget refuses to load](#when-the-widget-refuses-to-load)).
2. **Is the tag in the page?** View the source of the live page, not your template. Site builders and tag managers sometimes strip or delay scripts.
3. **Is `data-bot` present and correct?** Without it the script does nothing and logs nothing.
4. **Did `widget.js` load?** A strict Content Security Policy or an ad blocker can stop it. Allow `https://services.amomic.in` in `script-src` and `connect-src`.
5. **Is something covering it?** A cookie banner or cart button in the same corner can hide the launcher. Switch **Position** in Appearance.
:::

::: details It works in the console preview but not on my site
The preview skips the live check. Your site doesn't. Click **Set live**, or enable the web deployment on the agent's **Deployments** tab.
:::

::: details It works on localhost but not on the live site
Your production domain isn't allowed. Add the parent domain to **Allowed websites** and click **Save changes**.
:::

::: details It works on the main domain but not on another site
A listed domain covers its own subdomains only. `support.veloriahome.in` doesn't cover `veloria-service.in`. Add each separate domain.
:::

::: details My last changes aren't showing
Greeting bubble, Remember conversations, restart, lead form and allowed websites only take effect when you click **Save changes** on Install. Open the wizard, check them, and save from the Install step. Then reload your page.
:::

::: details The chat is empty when a visitor comes back
Either **Remember conversations** is off, the **Remember for** window has passed since the last message, or the visitor cleared site data or used a private window.
:::

::: details The wrong widget appears, or a second tag does nothing
Only the first widget tag on a page loads. If two templates each add a tag, the one that renders first wins and the other is ignored, even when they point at different widgets. Keep one tag per page. A second chat button on the page comes from another tool or your own custom UI, not from a second widget tag.
:::

## Next

::: cards

::: card Make it yours
[Customise the widget](/channels/web-chat-config) — identity, colours, launcher, greeting bubble and conversation memory.
:::

::: card Capture leads
[Turn visitors into contacts](/channels/web-chat-leads) the agent can follow up with on WhatsApp.
:::

::: card Build your own interface
[Use the headless client](/channels/web-chat-custom-ui) with your own components and the same deployment.
:::

::: card Manage the deployment
[Deployments](/build/deployments) — disable, enable or remove the web deployment.
:::

::: card See every channel
[Channels hub](/channels/overview) — which agent answers where.
:::

:::