> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a2v2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget JS API

> Embed the A2V2.ai chat widget and control it in the browser with A2V2Widget.init() and .destroy().

The chat widget is a self-contained JavaScript bundle you load on any website. It
mounts a floating chat bubble in an isolated container (a Shadow DOM), so it won't
clash with your site's styles and isn't affected by them. This page is the
developer reference for the widget's loader and its `window.A2V2Widget` API. For the
copy-paste install most sites need, see [Embed & Install](/embed/install).

## The loader script

Add the loader to your page. It detects its own host, loads the widget bundle, and
auto-initializes when a config object is present.

```html theme={null}
<script src="https://chat-widget.a2v2.ai/embed.js"></script>
```

When `embed.js` runs, it:

1. Guards against loading twice on the same page.
2. Loads the widget bundle (`a2v2-widget.js`) from the same host.
3. Once the bundle is ready, calls `A2V2Widget.init(window.A2V2WidgetConfig)` if a
   config object has been set.

## Configure the widget

Set `window.A2V2WidgetConfig` before (or alongside) the loader. With this in place,
the widget auto-initializes — you don't have to call `init()` yourself.

```html theme={null}
<script>
  window.A2V2WidgetConfig = { chatbotId: "<AGENT_ID>" };
</script>
<script src="https://chat-widget.a2v2.ai/embed.js"></script>
```

### `A2V2WidgetConfig` fields

| Field       | Type   | Required | Description                                                                   |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `chatbotId` | string | Yes      | The ID of the agent to load. Find it on the agent's **Embed/Install** screen. |

<Note>
  `chatbotId` is the only configuration field the widget reads today. The widget's
  appearance, welcome message, and visibility are controlled from the dashboard
  (see [Appearance](/customize/appearance) and [Visibility](/embed/visibility)), not
  from this config object. Additional config fields are **not currently supported** —
  if you need to pass more options at embed time, confirm availability with
  [support](mailto:support@a2v2.ai).
</Note>

<Warning>
  If `chatbotId` is missing, the widget logs an error to the browser console and does
  not mount. Double-check the value matches your agent's ID exactly.
</Warning>

## The `window.A2V2Widget` API

Once `a2v2-widget.js` has loaded, it exposes a global `A2V2Widget` object.

### `A2V2Widget.init(config)`

Mounts the widget. Pass an object with at least `chatbotId`.

```html theme={null}
<script>
  window.A2V2Widget.init({ chatbotId: "<AGENT_ID>" });
</script>
```

* Calling `init()` again while the widget is already mounted is ignored (it guards
  against double-initialization).
* The widget renders into a fixed, full-viewport container layered above your page,
  with pointer events limited to the bubble and chat panel.

### `A2V2Widget.destroy()`

Unmounts the widget and removes the elements it added to the page.

```html theme={null}
<script>
  window.A2V2Widget.destroy();
</script>
```

Use `destroy()` when you need to remove the widget dynamically — for example, on a
route change in a single-page app, or when a visitor opts out.

## Use cases

<Tabs>
  <Tab title="Static / auto-init">
    The simplest setup. Set the config, drop in the loader, done.

    ```html theme={null}
    <script>
      window.A2V2WidgetConfig = { chatbotId: "<AGENT_ID>" };
    </script>
    <script src="https://chat-widget.a2v2.ai/embed.js"></script>
    ```
  </Tab>

  <Tab title="Single-page app">
    Mount on a specific route and clean up when leaving it.

    ```javascript theme={null}
    // when entering a page where the widget should appear
    window.A2V2Widget?.init({ chatbotId: "<AGENT_ID>" });

    // when leaving that page
    window.A2V2Widget?.destroy();
    ```

    Make sure `a2v2-widget.js` has loaded before you call `init()` — keep the
    `embed.js` loader on the page, or check that `window.A2V2Widget` exists first.
  </Tab>

  <Tab title="Multiple agents">
    The widget namespaces its stored data per `chatbotId`, so loading different
    agents on different pages won't collide. Mounting two agents on the *same* page
    at once isn't a supported pattern — use one agent per page.
  </Tab>
</Tabs>

## Style isolation

The widget renders inside a Shadow DOM and injects its own styles there, so your
site's CSS can't reach the widget and the widget's CSS won't leak onto your site.
It also loads its own web font. A couple of things to know:

* The widget adds its font's stylesheet to the page `<head>`. If your site enforces
  a strict **Content-Security-Policy**, allow the widget's font and script sources
  or the widget may fail to load or style correctly.
* Some overlay elements (dropdowns, dialogs) render at the top of the page and are
  layered above other content using a very high stacking order.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bubble never appears">
    Confirm `window.A2V2WidgetConfig` (or your `init()` call) includes a valid
    `chatbotId`, that the loader script isn't blocked, and check the browser console
    for an A2V2 Widget error.
  </Accordion>

  <Accordion title="'chatbotId is required' in the console">
    The config was set without a `chatbotId`, or `init()` was called with an empty
    value. Provide the agent's ID.
  </Accordion>

  <Accordion title="init() does nothing">
    The widget bundle may not have loaded yet, or the widget is already mounted.
    Ensure `embed.js` has run and `window.A2V2Widget` exists before calling `init()`,
    and call `destroy()` before re-initializing.
  </Accordion>

  <Accordion title="Fonts or styles look wrong under a strict CSP">
    Allow the widget's font and script sources in your Content-Security-Policy.
  </Accordion>

  <Accordion title="A new version isn't showing up">
    Your site or CDN may be caching the page. Hard-refresh and clear any site/CDN
    cache after embedding.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Embed & Install" icon="rocket" href="/embed/install">
    The no-code snippets for link, iframe, and chat bubble.
  </Card>

  <Card title="Install on platforms" icon="puzzle-piece" href="/widget/install-platforms">
    Add the widget to WordPress, Webflow, Shopify, and more.
  </Card>

  <Card title="Appearance" icon="palette" href="/customize/appearance">
    Control how the widget looks and greets visitors.
  </Card>

  <Card title="API Overview" icon="circle-info" href="/api/overview">
    The Open API for server-to-server integration.
  </Card>
</CardGroup>