Install the widget

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.

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.

<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 #

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.

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:

Visitors see the new look on their next page load.

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.

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

// 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" />

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:

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.

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:

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

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.

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.

Opening and closing it from your own UI #

The widget exposes two methods on the page:

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

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

<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.

What the visitor's browser stores #

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

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.

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 #

Next #