Web Widget

A floating chat widget powered by your Bothive agent — drop one script tag onto any page and you’re live.

Quick embed

Add your agent to any website in 30 seconds:

<!-- 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

Open your bot in the Bothive dashboard
Go to Channels → Web Widget
Copy your Bot ID
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

<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:

<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>

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.

React / Next.js integration

// 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;
}

// In your layout.tsx
import { BothiveWidget } from '@/components/BothiveWidget';

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

Control the widget programmatically:

// 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'));

What data does the widget store?

How to disable analytics

Add analytics: false to BothiveConfig. This disables all usage tracking and event logging.

Start Here

Getting Started

Core Concepts

Building Agents

Deployment & Operations

Teams & Organisations

Integrations

API Reference

Resources

Web Widget

Quick embed

Get your bot ID

Customization options

Full configuration example

Passing user identity

React / Next.js integration

Widget events (JavaScript API)

Next reads

Deploy to Channels

Telegram Bots

API Reference

​Web Widget

​Quick embed

​Get your bot ID

​Customization options

​Full configuration example

​Passing user identity

​React / Next.js integration

​Widget events (JavaScript API)

​Privacy and GDPR

​Next reads

Deploy to Channels

Telegram Bots

API Reference

Web Widget

Quick embed

Get your bot ID

Customization options

Full configuration example

Passing user identity

React / Next.js integration

Widget events (JavaScript API)

Privacy and GDPR

Next reads