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

# Installation

> Add a floating chat widget to any website

## Quick Start

Add this script tag to any page where you want the chat widget to appear:

```html theme={null}
<script src="https://embed.boostgpt.co/widget.js" data-bot-id="YOUR_BOT_UUID"></script>
```

That's it. A floating chat bubble will appear in the bottom-right corner of your page, styled with your agent's branding.

## Find Your Bot ID

1. Go to your agent dashboard
2. Navigate to **Deploy**
3. Your Bot ID is shown in the embed code snippet

## Data Attributes

You can configure the widget directly via data attributes on the script tag:

| Attribute                   | Description                                                 | Default        |
| --------------------------- | ----------------------------------------------------------- | -------------- |
| `data-bot-id`               | **(Required)** Your agent's UUID                            | —              |
| `data-position`             | Bubble position: `bottom-right` or `bottom-left`            | `bottom-right` |
| `data-open-style`           | Chat open behavior: `normal`, `sidepanel`, or `dock`        | `normal`       |
| `data-panel-width`          | Desktop sidepanel width in pixels                           | `400`          |
| `data-dock-width`           | Desktop agent dock width in pixels                          | `720`          |
| `data-push-page`            | Push the page when the sidepanel opens                      | `true`         |
| `data-presentation-enabled` | Allow media and files to open beside the sidepanel          | `true`         |
| `data-page-actions`         | JSON map of named safe page targets for guided walkthroughs | —              |
| `data-user-token`           | Signed JWT for SSO user identification                      | —              |

```html theme={null}
<script
  src="https://embed.boostgpt.co/widget.js"
  data-bot-id="YOUR_BOT_UUID"
  data-position="bottom-left"
></script>
```

## Sidepanel Layout

Use sidepanel mode when you want the agent to feel like a docked assistant instead of a floating modal:

```html theme={null}
<script
  src="https://embed.boostgpt.co/widget.js"
  data-bot-id="YOUR_BOT_UUID"
  data-open-style="sidepanel"
  data-panel-width="400"
  data-push-page="true"
></script>
```

When the sidepanel opens, BoostGPT reserves space on the side of the page. Normal page content responds automatically because the widget docks the root `html` element.

Fixed or sticky page chrome may sit outside normal layout flow. If a fixed header or nav does not move with the page, mark it explicitly:

```html theme={null}
<nav data-boostgpt-push class="fixed w-full z-50 top-0 left-0">
  ...
</nav>
```

Use `data-boostgpt-push` only for fixed, sticky, or absolutely positioned elements that should resize with the docked page. Regular content does not need it.

## Agent Dock Layout

Use dock mode when you want the widget to feel like the hosted agent input: a centered prompt bar at the bottom of the page that expands into a wider chat panel.

```html theme={null}
<script
  src="https://embed.boostgpt.co/widget.js"
  data-bot-id="YOUR_BOT_UUID"
  data-open-style="dock"
  data-dock-width="720"
></script>
```

Dock mode uses your agent placeholder and conversation starters when available. It does not push the page; choose sidepanel mode when you need the page to resize beside the chat.

For guided page walkthroughs, you can define named targets that the agent may scroll to, highlight, or focus:

```html theme={null}
<script
  src="https://embed.boostgpt.co/widget.js"
  data-bot-id="YOUR_BOT_UUID"
  data-open-style="sidepanel"
  data-page-actions='{"pricing":{"selector":"#pricing","label":"Pricing"},"demo":{"selector":"[data-boostgpt-action=\"schedule-demo\"]","label":"Schedule demo"}}'
></script>
```

## Framework Setup

<CodeGroup>
  ```html HTML theme={null}
  <script src="https://embed.boostgpt.co/widget.js" data-bot-id="YOUR_BOT_UUID"></script>
  ```

  ```jsx Next.js theme={null}
  // app/layout.tsx (or pages/_app.tsx)
  import Script from 'next/script'

  export default function RootLayout({ children }) {
    return (
      <html>
        <body>
          {children}
          <Script
            src="https://embed.boostgpt.co/widget.js"
            data-bot-id="YOUR_BOT_UUID"
            strategy="afterInteractive"
          />
        </body>
      </html>
    )
  }
  ```

  ```js Nuxt.js theme={null}
  // plugins/boostgpt.js
  export default () => {
    (function() {
      var d = document;
      var s = d.createElement('script');
      s.src = 'https://embed.boostgpt.co/widget.js';
      s.setAttribute('data-bot-id', 'YOUR_BOT_UUID');
      s.async = 1;
      d.getElementsByTagName('head')[0].appendChild(s);
    })();
  };

  // nuxt.config.js
  plugins: [
    { src: '~/plugins/boostgpt.js', mode: 'client' }
  ]
  ```

  ```jsx React theme={null}
  // App.jsx (or any root component)
  import { useEffect } from 'react';

  function App() {
    useEffect(() => {
      const script = document.createElement('script');
      script.src = 'https://embed.boostgpt.co/widget.js';
      script.setAttribute('data-bot-id', 'YOUR_BOT_UUID');
      script.async = true;
      document.head.appendChild(script);
      return () => script.remove();
    }, []);

    return <div>{/* your app */}</div>;
  }
  ```

  ```vue Vue theme={null}
  <!-- App.vue -->
  <script setup>
  import { onMounted, onUnmounted } from 'vue'

  let script = null

  onMounted(() => {
    script = document.createElement('script')
    script.src = 'https://embed.boostgpt.co/widget.js'
    script.setAttribute('data-bot-id', 'YOUR_BOT_UUID')
    script.async = true
    document.head.appendChild(script)
  })

  onUnmounted(() => {
    if (script) script.remove()
  })
  </script>
  ```

  ```svelte SvelteKit theme={null}
  <!-- +layout.svelte -->
  <script>
    import { onMount } from 'svelte';

    onMount(() => {
      const script = document.createElement('script');
      script.src = 'https://embed.boostgpt.co/widget.js';
      script.setAttribute('data-bot-id', 'YOUR_BOT_UUID');
      script.async = true;
      document.head.appendChild(script);
      return () => script.remove();
    });
  </script>

  <slot />
  ```
</CodeGroup>

## Programmatic Initialization

For more control, initialize the widget via JavaScript:

```html theme={null}
<script src="https://embed.boostgpt.co/widget.js"></script>
<script>
  boostgpt.init({
    botId: 'YOUR_BOT_UUID',
    position: 'bottom-right',
  });
</script>
```

## How It Works

1. The script fetches your agent's branding (accent color, avatar, greeting messages) from the BoostGPT API
2. It injects a floating bubble button styled with your agent's accent color and avatar
3. Greeting messages from your branding settings appear as stacked chat bubbles above the button
4. When clicked, an iframe opens with your agent's full chat experience
5. The chat supports all features: streaming, tools, file uploads, workspaces, and custom interfaces

## Enable the Widget

Before the embed code appears on your Deploy page, enable the widget in your agent's settings:

1. Go to **Branding** → **Design** tab
2. Scroll to the **Chat Widget** section
3. Toggle **Enable Widget** on
4. Configure position and auto-open behavior