Skip to main content

​
Web Widget

Add a chat widget to your website so visitors can ask questions and get instant answers from your knowledge base.
BestChatBot chat widget open on a real website showing a conversation

​
What You Get

  • One line of code — paste a script tag and you’re done
  • Dedicated knowledge base for your website
  • Real-time streaming — answers appear word by word
  • Customizable colors to match your brand
  • Mobile friendly — full-screen on small devices
  • No impact on your site — runs in an isolated Shadow DOM
  • Response tracking — all widget conversations appear in your dashboard

​
Prerequisites

Before adding the widget to your website, make sure you have:
A BestChatBot account with an active workspace
Content in your knowledge base (documents or URLs)
Access to edit the HTML of the website where you want the widget
Each workspace is tied to one platform. If you already have a Discord workspace, create a separate workspace for your web widget.

​
Create Your Widget

Choose Platform

From your workspace, you’ll see the Choose Platform dialog. Select Web Widget to embed chat on your website.
Choose Platform dialog showing Discord and Web Widget options

Configure Your Widget

Fill in the setup form:
  • Name — a label for your widget (e.g., “My Website Widget”)
  • Allowed Origins — the domains where the widget can run, one per line. Supports wildcards (*.example.com). Leave empty to allow all.
  • Primary Color — your brand color in hex (e.g., #F97316)
Click Create Widget when ready.
Configure Web Widget form with Name, Allowed Origins, and Primary Color fields

View Your Widget

After creation, your widget appears in the Web Widgets page. Each widget card shows:
  • Name and status (Active/Inactive)
  • Active toggle to enable or disable the widget
  • Color indicator showing your brand color
  • Quick actions: embed code <> and settings ⚙
Widget Manager showing a widget card with status, color, and action buttons
Click the globe icon in the sidebar to go directly to the Web Widgets page.

​
Get Your Embed Code

Click the embed code button (<>) on your widget card, or go to Widget Settings → Installation tab. You’ll see a ready-to-paste snippet:
Embed Code dialog showing the script tag with instructions
The snippet looks like this: 
<script
  src="https://bestchatbot.io/widget/v1/chat.js"
  data-api-key="rk_live_xxxxxxxxxxxxxxxxxxxx"
  defer>
</script>

​
Install on Your Website

Paste the snippet into your website’s HTML, just before the closing </body> tag: 
<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <!-- Your website content -->

    <!-- BestChatBot Widget -->
    <script
      src="https://bestchatbot.io/widget/v1/chat.js"
      data-api-key="rk_live_xxxxxxxxxxxxxxxxxxxx"
      defer>
    </script>
  </body>
</html>
That’s it. The widget will appear as a floating chat bubble in the bottom-right corner of your site.
Never share or modify the data-api-key value. It’s your widget’s unique identifier.

​
Platform-Specific Instructions

  1. Go to Appearance → Theme File Editor (or use a plugin like “Insert Headers and Footers”)
  2. Open footer.php
  3. Paste the snippet just before </body>
  4. Save changes
Alternatively, use a plugin like WPCode to insert the snippet site-wide without editing theme files.
  1. Go to Online Store → Themes → Edit Code
  2. Open theme.liquid
  3. Paste the snippet just before </body>
  4. Save
  1. Go to Settings → Custom Code
  2. Click Add Custom Code
  3. Paste the snippet
  4. Set placement to Body - End
  5. Apply to All Pages
  1. Go to Settings → Advanced → Code Injection
  2. Paste the snippet in the Footer field
  3. Save
Add the script tag to your root layout or use the next/script component:
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://bestchatbot.io/widget/v1/chat.js"
          data-api-key="rk_live_xxxxxxxxxxxxxxxxxxxx"
          strategy="lazyOnload"
        />
      </body>
    </html>
  )
}
Paste the snippet before </body> in your HTML file. Works with any website that supports custom HTML.

​
How It Works

Once installed, the widget works like this:
  1. Page loads → the script loads from BestChatBot’s servers
  2. Widget appears → a chat bubble shows in the bottom-right corner
  3. Visitor clicks → the chat window opens
  4. Visitor asks a question → the widget sends it to your knowledge base
  5. Answer streams in → the response appears word by word in real time
  6. Sources shown → relevant sources from your knowledge base are listed (expandable)

​
Conversation Memory

The widget remembers the conversation within the same browser session. If a visitor navigates to another page, their chat history is preserved. Clicking the + button in the header starts a fresh conversation.
Conversation history is stored in the visitor’s browser (localStorage). It’s never shared between visitors or sent to third parties.

​
Widget Settings

Click the settings button (⚙) on your widget card to open the configuration panel. It has three tabs:

​
Configuration Tab

Change your brand color and allowed domains after creation. Primary Color — Choose your brand color using the color picker or enter a hex value (e.g., #F97316). The widget automatically adjusts:
  • Chat bubble accent
  • User message border
  • Send button color
  • Text contrast (white or black) based on your color
Allowed Origins — Enter the domains where the widget is allowed to run, one per line. This prevents unauthorized use of your embed code.
FormatExampleWhat It Matches
Exact URLhttps://example.comOnly that exact domain
Wildcardhttps://*.mysite.comAny subdomain of mysite.com
Supports wildcards like *.example.com to cover all subdomains. You cannot use * alone.
Click Save Changes to apply.

​
Installation Tab

View and copy your embed code snippet. Same as clicking the <> button on the widget card.

​
Danger Zone Tab

Danger Zone tab showing Regenerate API Key option
Regenerate API Key — If you suspect your API key has been compromised, click Regenerate Key. This:
  • Immediately invalidates the current API key
  • Generates a new one
  • Requires you to update the snippet on your website
The old key stops working immediately. Update your website right away to avoid downtime.

​
”Powered by BestChatBot” Badge

The footer badge is shown by default on the Free and Starter plans. Upgrade to Pro or Business to hide it.
PlanBadge
FreeShown
StarterShown
ProHidden
BusinessHidden

​
Monitoring Widget Conversations

All conversations from your web widget appear in the Bot Responses page of your dashboard. Use the Web filter to see only widget conversations.
Bot Responses page filtered to show Web widget conversations
Click any conversation to see the full exchange, including the user’s question and the bot’s complete response.
Detailed view of a widget conversation showing question and full bot response
Widget conversations are tagged with a Web badge, making them easy to distinguish from Discord conversations.

​
Mobile Experience

On screens smaller than 640px, the chat window automatically expands to full screen for a better mobile experience. The chat bubble adjusts its position to fit smaller screens.

​
Advanced: Programmatic API

For developers who want more control, the widget exposes a JavaScript API on window.BestChatBot after it loads.

​
Available Methods

MethodDescription
BestChatBot.open()Open the chat window
BestChatBot.close()Close the chat window
BestChatBot.toggle()Toggle open/close
BestChatBot.destroy()Remove the widget from the page entirely
BestChatBot.sendMessage(text)Send a message programmatically (opens the window)
BestChatBot.onReady(callback)Run a function when the widget is ready
BestChatBot.onMessage(callback)Run a function when a new message arrives

​
Examples

Open the widget when a button is clicked: 
<button onclick="BestChatBot.open()">
  Chat with us
</button>
Send a pre-filled question: 
<button onclick="BestChatBot.sendMessage('How do I reset my password?')">
  Help with password
</button>
Wait for the widget to be ready: 
BestChatBot.onReady(() => {
  console.log('Widget is ready!')
})
The API is only available after the widget script has loaded. If you need to call it immediately, use onReady() to wait for initialization.

​
Compatibility

The widget works on all modern browsers:
BrowserSupported
Chrome 80+✅
Firefox 80+✅
Safari 14+✅
Edge 80+✅
Mobile Chrome✅
Mobile Safari✅
Internet Explorer❌
The widget uses Shadow DOM for style isolation, which means it won’t conflict with your website’s CSS, and your CSS won’t affect the widget.

​
Troubleshooting

  • Check that the data-api-key is correct
  • Verify your domain is in the Allowed Origins list (Widget Settings → Configuration)
  • Open browser DevTools (Console tab) and look for [BestChatBot] warnings
  • Make sure the script tag has the defer attribute
  • Check that the widget is set to Active in the Widget Manager
  • Check that your knowledge base has content and has been rebuilt
  • Look for errors in the browser Console
  • Verify your subscription is active
The widget runs inside a closed Shadow DOM, so conflicts are extremely rare. If you see issues:
  • Check that you don’t have a global * { all: unset } rule
  • Make sure no script is removing the #bestchatbot-widget-host element
The script tag loads on every page where it’s included. To limit it:
  • Add the snippet only to specific page templates
  • Or use conditional loading with JavaScript:
if (window.location.pathname === '/support') {
  const script = document.createElement('script')
  script.src = 'https://bestchatbot.io/widget/v1/chat.js'
  script.setAttribute('data-api-key', 'rk_live_xxxx')
  script.defer = true
  document.body.appendChild(script)
}

​
Next Steps

Upload Documents

Add content for the widget to answer from.

Add URLs

Scrape your website content into the knowledge base.

Pricing Plans

Check plan features including widget limits.

Discord Integration

Set up a Discord bot in a separate workspace.