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

# Install the widget

> One script tag puts the chat bubble on every page of your site.

`widget.js` is the only thing that goes on your site. It is about 6 KB gzipped, draws a launcher, and opens the conversation in an iframe. Paste it immediately before the closing `</body>` tag of the layout every page shares:

```html theme={null}
<script src="https://wiredesk.ai/widget.js" data-widget="wk_..." async></script>
```

Your widget key is on the agent's **Install** page, already filled in to the snippet there. A widget key is public — anyone can read it from your page source. To keep it from working elsewhere, set [allowed domains](/docs/widget/allowed-domains).

The iframe is not created until a visitor shows intent — hover, focus, touch or click — so a page nobody chats on loads one small script and nothing else. Whether the panel is open is kept per tab, so clicking through to another page does not close a conversation in progress.

## By platform

<Tabs>
  <Tab title="HTML">
    Paste the snippet immediately before `</body>` in your site's layout or template. Publish, then load any page.
  </Tab>

  <Tab title="Google Tag Manager">
    1. In your GTM workspace, choose **Tags → New → Custom HTML**.
    2. Paste the snippet into the HTML box exactly as it is.
    3. Set the trigger to **All Pages**, leave **Support document.write** off, then **Save** and **Submit** to publish the container.
  </Tab>

  <Tab title="WordPress">
    Install **WPCode** or **Insert Headers and Footers** and paste the snippet into the Footer / Body box.

    Or, in a child theme, add it to `footer.php` just before `</body>`. Editing the parent theme works until the next update overwrites it.

    If your site caches aggressively (WP Rocket, LiteSpeed), purge the cache once after saving.
  </Tab>

  <Tab title="Shopify">
    1. **Admin → Online Store → Themes → ⋯ → Edit code**.
    2. Open **Layout → theme.liquid** and paste the snippet just above `</body>`.
    3. Save. Checkout pages are served separately — add the same line under **Settings → Checkout → Order status page scripts** if you want the widget there too.
  </Tab>

  <Tab title="Webflow">
    **Project Settings → Custom Code → Footer Code**, paste the snippet, save, then publish the site. Custom code only runs on the published site, never in the designer preview.
  </Tab>

  <Tab title="Squarespace">
    **Settings → Advanced → Code Injection**, and paste the snippet into the Footer box. Needs a Business plan or above.
  </Tab>

  <Tab title="React / Next.js">
    In the Next.js App Router, add it to the root layout so it survives client-side navigation:

    ```tsx app/layout.tsx theme={null}
    import Script from "next/script";

    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://wiredesk.ai/widget.js"
              data-widget="wk_..."
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    In Vite or any other single-page app, put the plain snippet in `index.html` before `</body>`. The widget lives outside React's tree, so a route change never unmounts it.
  </Tab>
</Tabs>

## Per-page overrides

The widget's look is set on the agent's **Playground** page. A single page can override it, either with an attribute on the script tag or with a field on `window.wiredeskSettings` set before the script loads. Each override applies to that page only.

| Attribute                        | `wiredeskSettings` field | Effect                                               |
| -------------------------------- | ------------------------ | ---------------------------------------------------- |
| `data-widget`                    | `key`                    | The widget key. The only required one.               |
| `data-side="left"`               | `side`                   | Puts the launcher in the bottom-left corner.         |
| `data-color="#0b5fff"`           | `launcherColor`          | Overrides the launcher colour.                       |
| `data-label="Need help?"`        | `launcherLabel`          | Gives the bubble a label instead of an icon.         |
| `data-offset-x="24"`             | `offsetX`                | Gap from the side of the window, in px.              |
| `data-offset-y="96"`             | `offsetY`                | Lifts it above a cookie bar or a sticky footer.      |
| `data-z-index="900"`             | `zIndex`                 | Puts it under an overlay of yours that matters more. |
| `data-hide-on-mobile="true"`     | `hideOnMobile`           | Hides the widget on phones on this page.             |
| `data-mobile-fullscreen="false"` | `mobileFullscreen`       | Opens as a panel rather than full screen on phones.  |
| `data-auto-open="15"`            | `autoOpenSeconds`        | Opens itself after this many seconds, once per tab.  |

```html theme={null}
<script>
  window.wiredeskSettings = { side: "left", offsetY: 96 };
</script>
<script src="https://wiredesk.ai/widget.js" data-widget="wk_..." async></script>
```

A second copy of the script on the same page does nothing, so a duplicate tag never draws a second bubble.

## It is not showing up

Work through [the chat bubble is not showing up](https://wiredesk.ai/help/the-chat-bubble-is-not-showing-up) in the help centre. The usual causes are a tag manager container that was never published, a page cache serving the old HTML, or a page that is not on the widget's [allowed domains](/docs/widget/allowed-domains).
