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

# Web Widget

> Embed a Bothive agent on any website — no backend required.

<div className="hero-container">
  <h1 className="hero-title">
    Web Widget
  </h1>

  <p className="hero-subtitle">
    A floating chat widget powered by your Bothive agent — drop one script tag onto any page and you're live.
  </p>
</div>

## Quick embed

Add your agent to any website in 30 seconds:

```html theme={null}
<!-- Paste before </body> in your HTML -->
<script>
  window.BothiveConfig = {
    botId: 'your-bot-id',         // From your bot dashboard
    position: 'bottom-right',     // bottom-right | bottom-left
    primaryColor: '#ffffff',      // Match your brand
    greeting: 'Hey! How can I help you today?'
  };
</script>
<script src="https://cdn.bothive.cloud/widget.js" async></script>
```

That's it. The widget loads asynchronously — zero impact on your page performance.

## Get your bot ID

1. Open your bot in the [Bothive dashboard](https://bothive.cloud/dashboard)
2. Go to **Channels** → **Web Widget**
3. Copy your **Bot ID**
4. Toggle the widget to **Active**

## Customization options

| Option          | Type      | Default               | Description                                      |
| --------------- | --------- | --------------------- | ------------------------------------------------ |
| `botId`         | `string`  | Required              | Your bot's unique ID                             |
| `position`      | `string`  | `bottom-right`        | Widget position: `bottom-right` or `bottom-left` |
| `primaryColor`  | `string`  | `#ffffff`             | Hex color for the widget button and header       |
| `greeting`      | `string`  | `Hi! How can I help?` | First message shown when widget opens            |
| `placeholder`   | `string`  | `Type a message...`   | Input placeholder text                           |
| `title`         | `string`  | Your bot's name       | Title shown in the widget header                 |
| `avatar`        | `string`  | Bothive default       | URL to a custom avatar image                     |
| `autoOpen`      | `boolean` | `false`               | Open the widget automatically after X seconds    |
| `autoOpenDelay` | `number`  | `5`                   | Seconds before auto-open                         |
| `hideOnMobile`  | `boolean` | `false`               | Hide widget on screens \< 768px                  |

## Full configuration example

```html theme={null}
<script>
  window.BothiveConfig = {
    botId: 'bot_abc123xyz',
    position: 'bottom-right',
    primaryColor: '#0ea5e9',
    greeting: " Welcome to Acme! I can help with billing, product questions, and getting started.",
    placeholder: 'Ask me anything...',
    title: 'Acme Support',
    avatar: 'https://yoursite.com/support-avatar.png',
    autoOpen: true,
    autoOpenDelay: 8,
    hideOnMobile: false,
    // Pass user identity for memory scoping (optional)
    userId: '{{CURRENT_USER_ID}}',
    userEmail: '{{CURRENT_USER_EMAIL}}'
  };
</script>
<script src="https://cdn.bothive.cloud/widget.js" async></script>
```

## Passing user identity

If you're logged-in users interacting with the widget, pass their identity so the agent has scoped memory:

```html theme={null}
<script>
  window.BothiveConfig = {
    botId: 'bot_abc123',
    // Server-rendered user data
    userId: '<%= current_user.id %>',
    userEmail: '<%= current_user.email %>',
    userMeta: {
      plan: '<%= current_user.plan %>',
      company: '<%= current_user.company %>'
    }
  };
</script>
```

<Info>
  When `userId` is provided, the widget uses it as the session ID — so the agent remembers each user's conversation history and persistent memory across visits.
</Info>

## React / Next.js integration

```tsx theme={null}
// components/BothiveWidget.tsx
'use client';

import { useEffect } from 'react';
import { useUser } from '@/hooks/useUser';

export function BothiveWidget() {
  const { user } = useUser();

  useEffect(() => {
    window.BothiveConfig = {
      botId: process.env.NEXT_PUBLIC_BOTHIVE_BOT_ID!,
      position: 'bottom-right',
      primaryColor: '#ffffff',
      userId: user?.id,
      userEmail: user?.email,
      userMeta: { plan: user?.plan }
    };

    const script = document.createElement('script');
    script.src = 'https://cdn.bothive.cloud/widget.js';
    script.async = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, [user]);

  return null;
}
```

```tsx theme={null}
// In your layout.tsx
import { BothiveWidget } from '@/components/BothiveWidget';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <BothiveWidget />
      </body>
    </html>
  );
}
```

## Widget events (JavaScript API)

Control the widget programmatically:

```javascript theme={null}
// Open the widget
window.Bothive.open();

// Close the widget
window.Bothive.close();

// Send a message programmatically
window.Bothive.sendMessage('I need help with my invoice');

// Listen to events
window.Bothive.on('open', () => console.log('Widget opened'));
window.Bothive.on('message', (msg) => console.log('User sent:', msg));
window.Bothive.on('close', () => console.log('Widget closed'));
```

## Privacy and GDPR

<AccordionGroup>
  <Accordion title="What data does the widget store?">
    The widget stores a session ID in `localStorage` to maintain conversation continuity. If `userId` is not provided, a random anonymous ID is generated. No cookies are set by default.
  </Accordion>

  <Accordion title="How to disable analytics">
    Add `analytics: false` to `BothiveConfig`. This disables all usage tracking and event logging.
  </Accordion>

  <Accordion title="GDPR compliance">
    Bothive is GDPR-compliant. Data is stored in EU data centers by default. You can request data deletion via the API or dashboard for any user session.
  </Accordion>
</AccordionGroup>

## Next reads

<CardGroup cols={3}>
  <Card title="Deploy to Channels" icon="signal" href="./deploy-to-channels" className="glass-effect" />

  <Card title="Telegram Bots" icon="telegram" href="./telegram-bots" className="glass-effect" />

  <Card title="API Reference" icon="code" href="../api/overview" className="glass-effect" />
</CardGroup>