Website Integration

Add an AI-powered chat to your website to provide instant customer support 24/7. The botBrains integration is customizable, lightweight, and easy to install - giving your visitors immediate access to answers without leaving your site.

Value Proposition

The website chat integration transforms your customer experience:

Instant Answers: Customers get immediate responses without waiting for email support or business hours
Reduced Bounce Rates: Visitors find answers in real-time instead of leaving to search elsewhere
Lead Capture: Engage prospects at the moment of interest with intelligent conversation
Seamless Integration: Works with your existing website without complex setup or code changes
Brand Consistency: Customize appearance to match your brand identity

Prerequisites

Before integrating, you’ll need:

A botBrains project with configured AI behavior and knowledge sources
A published frame (chat interface design)
Access to edit your website’s HTML
Basic familiarity with adding code snippets to your website

Integration Modes

botBrains offers three integration modes to fit different use cases. Choose the right mode based on your use case and page layout.

Decision Matrix

Mode	Best For	When to Use	When to Avoid
Launcher (Recommended)	General website integration	• Multi-page support across entire site • Non-intrusive engagement • Standard support widget • Mobile-responsive sites	• Pages where floating elements conflict • Full-page applications
Inline	Dedicated support pages	• FAQ pages • Contact/support pages • Application sidebars • Replacing traditional contact forms • Full control over placement and size	• General site-wide integration • When you want floating/minimizable chat
iFrame (Deprecated)	Legacy compatibility only	• Only if technical constraints prevent launcher/inline • Third-party embeds with strict isolation	• New integrations (use launcher or inline instead) • When you need Web SDK features • Mobile-optimized experiences

Mode Details

Launcher Mode (Recommended)

Floating chat button in corner of page
Minimizes to button when not in use
Works across all pages with single embed
Automatically responsive on mobile
Supports all Web SDK features

Inline Mode

Embeds directly into page content
Always visible (no minimize)
You control height/width via CSS
Ideal for dedicated support sections
Supports all Web SDK features

iFrame Mode (Deprecated)

Full-page iframe embed
Limited Web SDK support
Not recommended for new integrations
Use launcher or inline instead

You cannot use both launcher and inline modes on the same page. Choose one per page, though you can use different modes on different pages of your site.

Get Your Embed Code

Navigate to Channels in your botBrains project
Click on Web integration
Select your desired mode (Launcher, Inline, or iFrame)
Configure options as needed
Copy the generated code snippet

Launcher Mode Integration

Basic Setup

Add this code snippet before the closing </body> tag in your HTML:

<script type="text/javascript">
  window.$botbrains = window.$botbrains || []
  window.$botbrains.push(["set", "config", {
      "frameId": "your-frame-id"
  }]);
  (function(){
    d = document;
    s = d.createElement('script');
    s.src = 'https://chat.botbrains.io/loader.js';
    s.type = 'module';
    s.async = 1;
    d.getElementsByTagName('head')[0].appendChild(s);
  })();
</script>

Replace your-frame-id with your actual frame ID from the platform.

Configuration Options

You can customize the launcher behavior by adding options to the config object:

<script type="text/javascript">
  window.$botbrains = window.$botbrains || []
  window.$botbrains.push(["set", "config", {
      "frameId": "your-frame-id",
      "previewDelayMs": 5000,
      "cookieDomain": ".example.com",
      "sessionRefreshLifetime": 268320,
      "whatsappId": "your-whatsapp-id",
      "experimentalListConversations": false
  }]);
  (function(){
    d = document;
    s = d.createElement('script');
    s.src = 'https://chat.botbrains.io/loader.js';
    s.type = 'module';
    s.async = 1;
    d.getElementsByTagName('head')[0].appendChild(s);
  })();
</script>

Available Configuration Options

Option	Type	Default	Description
`frameId`	string	required	Your frame ID from botBrains
`previewDelayMs`	number	`3000`	Time in milliseconds to delay showing message previews (default 3 seconds)
`cookieDomain`	string	auto-detected	Domain for session cookies. Leave empty for automatic top-level domain detection (e.g., `.example.com` shares sessions across all subdomains)
`sessionRefreshLifetime`	number	`268320`	Session lifetime in minutes (default: 6 months)
`whatsappId`	string	-	WhatsApp integration ID issued by botBrains team
`experimentalListConversations`	boolean	`false`	Enable experimental UI for viewing and continuing multiple conversations

The previewDelayMs option only controls the delay before showing previews. To disable previews entirely, configure this in the Frame settings under the Appearance tab.

The cookieDomain option affects how user sessions are shared across your domain. By default, sessions are shared across all subdomains (e.g., www.example.com, app.example.com). Only set this explicitly if you need to limit session sharing to a specific subdomain.

Inline Mode Integration

Basic Setup

Inline mode requires two code snippets - one for the script and one for the container element.

Step 1: Add the Script

Add this before the closing </body> tag:

<script type="text/javascript">
  window.$botbrains = [];
  window.$botbrains.push(["set", "config", {
      "frameId": "your-frame-id",
      "mode": "inline",
      "selector": "#botbrains-inline-chat"
  }]);
  (function(){
    d = document;
    s = d.createElement('script');
    s.src = 'https://chat.botbrains.io/loader.js';
    s.type = 'module';
    s.async = 1;
    d.getElementsByTagName('head')[0].appendChild(s);
  })();
</script>

Step 2: Add the Container

Place this div element where you want the chat to appear:

<div id="botbrains-inline-chat" style="max-width: 56rem; height: 80vh;"/>

You control the height and width of the chat through the container’s CSS.

Important: You must choose either launcher mode or inline mode per page. Using both on the same page is not supported. However, you can use different modes on different pages of your website.

Configuration Options

Inline mode supports the same configuration options as launcher mode, plus:

Option	Type	Default	Description
`mode`	string	`"inline"`	Must be set to `"inline"` for inline mode
`selector`	string	`"#botbrains-inline-chat"`	CSS selector where the chat will be rendered (must be a valid `document.querySelector()` target)

All other options (previewDelayMs, cookieDomain, sessionRefreshLifetime, whatsappId, experimentalListConversations) work the same as in launcher mode.

iFrame Mode Integration (Deprecated)

Deprecated: iFrame mode provides limited functionality and does not support the Web SDK. Use launcher or inline mode instead for the best experience.

If you need to use iFrame mode for legacy compatibility:

<iframe
  src="https://chat.botbrains.io/loader?frameId=your-frame-id&mode=fullscreen"
  width="100%"
  height="100%"
  style="border: none; min-height: 500px;"
  allow="fullscreen; clipboard-write; clipboard-read; microphone https://chat.botbrains.io"
  frameborder="0"
/>

Platform-Specific Integration

WordPress

Go to Appearance > Theme File Editor
Select your theme’s footer.php file
Add the embed code before the closing </body> tag
Click Update File

Or use a plugin:

Install the “Insert Headers and Footers” plugin
Go to Settings > Insert Headers and Footers
Paste the embed code in the “Scripts in Footer” section
Click Save

Shopify

Go to Online Store > Themes
Click Actions > Edit code on your active theme
Find and open theme.liquid
Scroll to the bottom and add the embed code before </body>
Click Save

Webflow

Go to your project settings
Click on the Custom Code tab
Paste the embed code in the Footer Code section
Click Save Changes and republish your site

React/Next.js

// Add to your layout component or _app.tsx
useEffect(() => {
  window.$botbrains = window.$botbrains || [];
  window.$botbrains.push(["set", "config", {
    frameId: "your-frame-id",
    // Add other config options here
  }]);

  const script = document.createElement('script');
  script.src = 'https://chat.botbrains.io/loader.js';
  script.type = 'module';
  script.async = true;

  document.head.appendChild(script);

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

Customizing Appearance

Visual customization is done through the Frame settings in your botBrains project:

Navigate to Frames in botBrains
Click Edit on your frame
Configure in the Appearance tab:
- Colors: Primary color, background, text colors
- Position: Bottom right, bottom left (launcher mode only)
- Branding: Logo, avatar, welcome message
- Language: Widget text and labels
- Previews: Enable/disable message previews

Testing Your Integration

Before going live:

Preview Mode: Test the integration in a staging environment first
Responsive Design: Verify the chat works on mobile, tablet, and desktop
Browser Testing: Check compatibility across Chrome, Firefox, Safari, and Edge
Performance: Ensure the integration doesn’t slow down your page load
Functionality: Test conversations, escalations, and edge cases

Use Browser DevTools: Open your browser’s console to see any errors or warnings during testing.

Troubleshooting

Chat Not Appearing

If the chat doesn’t show up:

Check the code placement: Ensure the script is before the closing </body> tag
Verify frameId: Confirm your frame ID is correct in the config object
Check browser console: Look for JavaScript errors
Clear cache: Try hard-refreshing your page (Ctrl+Shift+R / Cmd+Shift+R)
Check frame status: Ensure the frame is published in botBrains
Inline mode: Verify the container element exists and has a valid selector

Performance Issues

If the integration slows down your site:

Async loading: The script already loads asynchronously with s.async = 1
Optimize frame: Reduce custom CSS and heavy assets in your frame design
Preview delay: Increase previewDelayMs to reduce initial loading impact

Styling Conflicts

If the chat looks broken:

CSS specificity: Your site’s CSS might be overriding chat styles
Z-index issues: Ensure the chat appears above other elements (especially in launcher mode)
Inline mode: Check that the container element has appropriate dimensions set

Configuration Not Applied

If your configuration changes aren’t working:

Clear cookies: Your browser may be caching an old session
Hard refresh: Clear browser cache with Ctrl+Shift+R / Cmd+Shift+R
Check syntax: Ensure your config object is valid JSON
Cookie domain: If using cookieDomain, verify it matches your domain structure

Best Practices

Start Simple: Begin with the basic integration and minimal configuration. Add advanced options only when needed.

Mobile-First: Test on mobile devices where space is limited. Consider using inline mode on mobile for FAQ pages.

Clear Welcome Message: Configure a welcome message in your frame that tells visitors what the AI agent can help with.

Session Management: The default 6-month session lifetime works well for most use cases. Only adjust if you have specific privacy or security requirements.

Test Before Launch: Always test the integration thoroughly in a staging environment before deploying to production.

Monitor Performance: Keep an eye on page load times to ensure the integration doesn’t negatively impact user experience.

Next Steps

After integrating:

Customize Your Frame - Design the perfect chat interface for your brand
Configure Escalations - Set up human handoff for complex issues
Monitor Conversations - Review how customers are using the chat
Analyze Topics - Discover what questions customers ask most

Support

Need help with integration?

Check our troubleshooting guide above
Contact support at support@botbrains.io

Getting Started

Core Concepts

Train

Deploy

Analyze

Guides

Security

Other

More

​Website Integration

​Value Proposition

​Prerequisites

​Integration Modes

​Decision Matrix

​Mode Details

​Get Your Embed Code

​Launcher Mode Integration

​Basic Setup

​Configuration Options

​Available Configuration Options

​Inline Mode Integration

​Basic Setup

​Step 1: Add the Script

​Step 2: Add the Container

​Configuration Options

​iFrame Mode Integration (Deprecated)

​Platform-Specific Integration

​WordPress

​Shopify

​Webflow

​React/Next.js

​Customizing Appearance

​Testing Your Integration

​Troubleshooting

​Chat Not Appearing

​Performance Issues

​Styling Conflicts

​Configuration Not Applied

​Best Practices

​Next Steps

​Support

Website Integration

Value Proposition

Prerequisites

Integration Modes

Decision Matrix

Mode Details

Get Your Embed Code

Launcher Mode Integration

Basic Setup

Configuration Options

Available Configuration Options

Inline Mode Integration

Basic Setup

Step 1: Add the Script

Step 2: Add the Container

Configuration Options

iFrame Mode Integration (Deprecated)

Platform-Specific Integration

WordPress

Shopify

Webflow

React/Next.js

Customizing Appearance

Testing Your Integration

Troubleshooting

Chat Not Appearing

Performance Issues

Styling Conflicts

Configuration Not Applied

Best Practices

Next Steps

Support