Skip to main content

Embeddable Bots

The Bots feature lets you create AI-powered chat assistants that you can embed on any external website with a single script tag. Each bot is linked to a Chat Persona, giving it scoped access to your knowledge base, and can be fully customised in appearance, behaviour, and AI settings.

Getting Started​

Open the Bots tab from the dashboard. The tab requires the bots_enabled capability on your subscription and the BOTS_MANAGE permission on your account.

The Bots area is organised into four subtabs:

SubtabPurpose
All BotsBrowse, search, and manage every bot in your workspace
ConfigurationCreate a new bot or edit an existing one
Embed CodeCopy the JavaScript snippet to deploy the bot on your site
AnalyticsMonitor sessions, messages, and embedding origins

An overview landing page displays aggregate stats (total bots, active bots, total sessions, total messages) and quick-action buttons for the most common tasks.

Interface Overview​

The overview page shows four stat cards at the top, followed by a quick-actions panel and a recent-bots list. Each bot entry displays its avatar, name, active/inactive status, linked persona, and session/message counts. Inline icon buttons let you preview the widget, copy embed code, or jump to configuration without leaving the page.

Creating a Bot​

  1. Click Create New Bot from the overview or the All Bots subtab

  2. Fill in the Basic Information section:

    • Name — the display name shown in the widget header
    • Slug — a URL-friendly identifier, unique within your tenant
    • Description — an internal note about the bot's purpose
    • Knowledge Persona — select a Chat Persona that determines which knowledge categories and vector indices the bot can access

  3. Configure Appearance:

    • Choose an avatar from the built-in icon gallery, upload a custom image (PNG, JPG, SVG, or WebP up to 5 MB), or paste an image URL
    • Set the primary colour used for the widget header and buttons
    • Write a greeting message displayed when the chat opens
    • Set the placeholder text shown in the message input
    • Choose the widget position (bottom-right or bottom-left)

  4. Adjust AI Configuration (optional):

    • Override the default chat model (leave blank to use the persona default)
    • Set the temperature slider (0.0 for deterministic, 1.0 for more creative responses)
    • Define the max tokens per response
    • Provide a custom system prompt to shape the bot's behaviour

  5. Set Security options:

    • Allowed origins — add one or more URLs that are permitted to embed the bot. Leaving this empty allows all origins (not recommended for production)
    • Rate limits — configure the maximum messages per hour per session and per day across all sessions
    • CAPTCHA — enable Google reCAPTCHA v3 verification for high-traffic bots and supply the site key and secret key

  6. Configure Behaviour switches in the sidebar:

    • Active — whether the bot is publicly reachable
    • Persistence — allow returning visitors to see their previous messages via localStorage
    • Show sources — display knowledge-base sources in bot responses
    • Show "Powered by" — display the Booga Enterprise branding footer
    • Max history messages — how many messages to store locally for persistence

  7. Click Create Bot to save. The bot is created in active state and is immediately available for embedding.

Managing Bots​

All Bots View​

The All Bots subtab displays every bot in a card grid. Use the search field to find bots by name, slug, or description, and the status filter to show only active or inactive bots.

Each card shows:

  • Avatar, name, and description
  • Active/inactive chip and linked persona
  • Session and message counts
  • Inline actions: copy embed code, preview, edit, analytics

A kebab menu on each card provides additional actions:

ActionEffect
EditOpen the Configuration subtab for this bot
Copy Embed CodeCopy the script tag to clipboard
PreviewOpen the bot widget in a new preview window
View AnalyticsJump to the Analytics subtab for this bot
Rotate Public KeyGenerate a new public key (invalidates all existing embeds using the old key)
DeletePermanently remove the bot and all its session data

Toggling a Bot On/Off​

Use the active switch on any bot card or in the Configuration sidebar to enable or disable the bot. Deactivated bots return a 404 to the public widget endpoint — existing embeds stop working until you reactivate.

Rotating the Public Key​

Each bot has a unique public key (format: bk_ followed by 24 hex characters) used in the embed snippet. If you suspect the key has been exposed or you want to invalidate all existing deployments, open the kebab menu and click Rotate Public Key. A confirmation dialog explains the impact. After rotation, update the embed code on every site that hosts the bot.

Embedding a Bot​

Getting the Embed Code​

  1. Open the Embed Code subtab
  2. Select the bot from the dropdown
  3. Choose the embed format:
    • Script Tag (recommended) — a self-contained <script> snippet you paste before </body>
    • ES Module — an import-based approach for modern JavaScript build pipelines
  4. Click Copy Code or the copy icon to copy the snippet to your clipboard

Installing the Widget​

Paste the script tag into your website's HTML, ideally just before the closing </body> tag. The widget loads asynchronously and does not block page rendering. Once loaded, a chat bubble appears in the configured position (bottom-right by default).

Programmatic Control​

After the widget initialises, you can control it from JavaScript:

boogaBot('open');     // Open the chat window
boogaBot('close');    // Close the chat window
boogaBot('toggle');   // Toggle open/close
boogaBot('destroy');  // Remove the widget entirely

Theme Overrides​

You can pass theme overrides at init time to match the bot's appearance to your website:

boogaBot('init', {
  botId: 'your-bot-slug',
  theme: {
    primaryColor: '#1976d2',
    fontFamily: 'Inter',
    borderRadius: 12
  }
});

Bot Analytics​

The Analytics subtab provides usage insights for a selected bot.

Summary Cards​

Four stat cards display at the top:

MetricDescription
Total SessionsAll-time unique visitor sessions
Total MessagesAll-time assistant responses
Active SessionsCurrently active (non-expired) sessions
Avg Messages / SessionAverage assistant messages per session

Messages Over Time​

A chart shows daily message counts for the selected period (7 or 30 days). Use the period selector to switch views. Hover over bars or points to see exact counts. Quick stats below the chart show messages today and this week.

Top Embedding Origins​

A table lists the websites where the bot is embedded, ranked by session count. Each row shows the origin URL, session count, and message count. This helps you understand where your bot is being used and which deployments are most active.

Security and Rate Limiting​

Origin Validation​

When you add URLs to the Allowed Origins list, the bot API validates the Origin header on every public request. Requests from unlisted domains receive a 403 Forbidden response. For local development, localhost origins are matched flexibly (port variations are allowed).

Important: Leaving the allowed origins list empty permits any domain to embed the bot. Always configure origins before deploying to production.

Rate Limiting​

Two layers of rate limiting protect bots from abuse:

  • Session rate limit — maximum messages per hour from a single anonymous session (default: 60). The hourly window resets automatically
  • Daily rate limit — maximum assistant messages per day across all sessions for the bot (default: 500)

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with X-RateLimit-* headers indicating the limit, current usage, and a Retry-After value.

CAPTCHA Protection​

For high-traffic or public-facing bots, enable reCAPTCHA v3 verification. This requires a Google reCAPTCHA site key and secret key, which you can obtain from the Google reCAPTCHA admin console. When CAPTCHA is enabled, every chat request must include a valid CAPTCHA token.

Anonymous Session Tracking​

Bot sessions are anonymous — no login is required. Each session is identified by a browser fingerprint hash (the raw fingerprint is never stored). This allows rate limiting and returning-visitor persistence without collecting personal data.

How Bots Use Personas and Knowledge​

Each bot is linked to a Chat Persona, which acts as the knowledge access control layer. The persona determines:

  • Which knowledge categories the bot can search
  • Which vector indices are available for semantic retrieval
  • The default chat model (which the bot can optionally override)
  • Feature toggles for knowledge search, web search, and file uploads

When a visitor sends a message, the bot retrieves relevant documents from the persona's accessible knowledge scope, combines them with the conversation history, and generates a response using the configured AI model. If Show Sources is enabled, the response includes references to the knowledge documents used.

Tip: Create a dedicated persona per bot to keep each embed's knowledge scope tightly scoped and consistent.

Best Practices​

  • Use dedicated personas — give each bot its own persona to isolate knowledge access and ensure consistent, on-brand responses
  • Configure allowed origins before production — restrict embedding to your own domains to prevent unauthorised use
  • Set reasonable rate limits — balance usability with abuse prevention; review analytics to tune limits
  • Write a clear system prompt — a well-crafted system prompt keeps bot responses focused and aligned with your brand voice
  • Monitor analytics regularly — check top embedding origins and message trends to spot anomalies or underperforming deployments
  • Rotate keys if compromised — if a public key is exposed, rotate it immediately and update all embed codes
  • Test in preview before embedding — use the preview button to verify appearance and behaviour before deploying to production

Troubleshooting​

Bot widget not loading​

Problem: The chat bubble does not appear on your website. Solution: Verify the embed script is placed before </body> and that the public key in the snippet matches the bot's current key. Open the browser console and check for JavaScript errors or CORS-related warnings. Confirm the bot is active in the dashboard.

CORS / Origin errors​

Problem: The widget loads but API requests fail with a 403 or CORS error. Solution: Add your website's exact origin URL (including scheme and port, e.g., https://www.example.com) to the bot's Allowed Origins list. For local development, add http://localhost:3000 or whichever port you use.

Bot not responding​

Problem: Messages are sent but no response appears. Solution: Check that the bot is linked to an active Chat Persona with accessible knowledge categories. Verify AI services are running for your stack. Review the rate limit headers in the response — the bot may have hit a daily or session limit.

Rate limit exceeded​

Problem: Users see a "rate limit exceeded" error. Solution: Increase the per-session or per-day rate limits in the bot's Security settings. If the limit was hit by legitimate traffic, consider splitting the workload across multiple bots.

Public key no longer working​

Problem: An embed that was previously working now returns 404. Solution: The public key may have been rotated. Open the Embed Code subtab, copy the updated snippet with the new key, and redeploy it to your website.

⏱️ Read time: 12 minutes | 📊 Difficulty: intermediate | 🔄 Last updated: 2026-03-30