Skip to main content

Script tag install

The simplest way to embed MimicBot is with a single <script> tag. This page is the exhaustive attribute reference for the launcher. For a guided install walkthrough, see Install the widget.

Canonical snippet​

<script
  type="module"
  crossorigin="anonymous"
  src="https://api.mimicbot.app/v3/widget.js"
  data-bot-id="bot_YOUR_PUBLIC_ID"
></script>

Paste it at the end of <body> on any page you want MimicBot to appear on. The launcher is safe to ship on server-rendered pages, hydrated React trees, and static HTML — it mounts into its own fixed-position host element outside your app's render tree.

Attributes​

AttributeRequiredDefaultDescription
type="module"yes—Forces the browser to load the launcher as an ES module. The v3 build relies on native ESM.
crossorigin="anonymous"yes—Required for the CDN's cross-origin response. Without it the browser refuses to evaluate the script under strict CORS rules.
srcyes—The versioned launcher URL. Always use /v3/widget.js unless you are intentionally pinned to an older release.
data-bot-idyes—The bot's publicId, shaped like bot_<10 chars>. Read from the POST /api/bots response.
data-api-basenoScript originOverride the API origin the widget talks to. Only needed when you self-host the MimicBot API at a different domain than the one serving widget.js.

When data-api-base is omitted, the launcher derives the API origin from its own src URL. When both are absent, it falls back to window.location.origin.

Mount guarantees​

The launcher guards against double-mount via a Symbol.for('@agents/widget.mounted') marker on window. If the script tag is injected twice (e.g., a single-page app that re-renders its <head>), the second load is silently ignored. This makes it safe to include MimicBot in a site-wide layout without reference counting.

The launcher creates one <div data-agents-widget> inside document.body, attaches an open shadow root, and renders the launcher bubble inside the shadow. Your site's CSS and JS cannot reach into the shadow tree, and MimicBot's Tailwind reset cannot reach out. The host div is position:fixed with pointer-events:none; only the bubble and chat panel re-enable pointer events on themselves, so the rest of your page stays fully interactive.

Launcher budget​

The launcher (/v3/widget.js) is about 30 KB gzipped. It ships zero React — just enough vanilla DOM to render the bubble and register a click handler. On click it dynamic-imports the chat panel chunk, which brings React, the AI SDK, and the full BotChat component with it. Your first-paint cost on the host site is the launcher only; the heavy code is on-demand.

CI enforces the 30 KB ceiling on every PR.

Versioning​

Published versions:

PathStatusNotes
/v3/widget.jscurrentRecommended for all new installs. Modern UIMessageStream wire protocol, shadow DOM isolation, form-replay layers 1–3.
/v2/widget.jslegacyKept live for at least 30 days after each major release. Will eventually be retired.

When a major version ships, the previous version continues to work during the rollout window so customer pages with older snippets keep responding while operators rotate their embeds.

Multiple bots on the same page​

Not supported. A page should load exactly one MimicBot launcher. The MOUNT_KEY guard ensures only the first data-bot-id on the page is honored; additional launcher script tags are no-ops. To A/B test between bots, swap the data-bot-id attribute server-side between page loads.