Skip to main content

​
Website Chat Widget

Frames are the visual chat interface that your website visitors interact with. Think of them as the “face” of your AI - they control how the chat widget looks, behaves, and presents itself across different pages and devices. A well-designed frame creates an engaging, on-brand experience that encourages visitors to get the help they need.

​
Why Frames Matter

Your chat widget is often the first point of contact between your AI and your customers. The right frame design:
  • Increases engagement - Visitors are more likely to use a chat that looks trustworthy and professional
  • Reinforces brand identity - Match your website’s colors, tone, and style seamlessly
  • Adapts to context - Show different messages and suggestions based on which page visitors are viewing
  • Removes friction - Guide users with clear welcome messages and suggested questions
  • Works everywhere - Delivers consistent experience across desktop, tablet, and mobile devices
A thoughtfully designed frame can increase chat adoption by 3-5x compared to default designs. Users trust and engage with interfaces that feel native to your brand.

​
Frame Architecture

Understanding the frame structure helps you customize effectively: 
Frame (Widget Configuration)
├─ General Settings
│  ├─ Assistant name and images
│  ├─ Security (allowed origins, whitelisted IPs)
│  └─ Features (image upload, preview popup)
├─ Theme Settings
│  ├─ Light mode colors
│  └─ Dark mode colors
├─ Messages (Localization)
│  ├─ Start message per language
│  └─ Suggested questions per language
├─ Launcher Settings
│  ├─ Button position and spacing
│  └─ Button color
└─ Rules (Conditional Appearance)
   ├─ URL pattern matching
   ├─ Platform targeting (mobile/desktop)
   └─ Custom messages per page

​
Accessing Frame Settings

Navigate to Frames in your project to:
  1. View existing frames - See all configured chat widgets for your project
  2. Create new frames - Add additional widgets for different websites or environments
  3. Edit frame settings - Customize appearance, messages, and behavior
  4. Get embed code - Copy the code snippet to add the widget to your website
Most projects start with one default frame. You can create additional frames for:
  • Different brands or sub-sites
  • Testing environments (staging vs production)
  • Regional variations with different languages

​
General Settings

​
Assistant Identity

Configure how your AI agent presents itself to visitors.
SettingPurposeFormat/Requirements
Assistant NameDisplayed in conversation headersAny text (e.g., “Support Bot”, “Emma”)
Assistant ImageAvatar next to AI messagesPNG/JPEG/SVG/WebP, 64x64px+, auto-compressed to 30KB
Header ImageOptional banner at top of chatPNG/JPEG/SVG/WebP, 400x80px recommended
Use your company logo as the assistant image for instant brand recognition.

​
Feature Configuration

Preview Suggestions: Display a popup with suggested questions after 5 seconds. Useful for proactively showing visitors what the AI can help with. Can be overridden per page using Rules. Allow Image Upload: Enable visitors to upload screenshots, product photos, or documents in conversations. Images are scanned and validated before processing.

​
Security Configuration

Allowed Origins: URLs permitted to embed this widget (CORS security). Format: https://example.com or wildcards https://*.example.com. Required for all domains where you’ll embed the widget.
The widget will not load on domains not listed in Allowed Origins. Always add your production and staging domains before deployment.
Whitelisted IPs: IP addresses granted higher request limits (e.g., office IPs for testing). Only whitelist IPs you fully control. Terms of Service URL and Privacy Policy URL appear as footer links in the chat widget. Always provide these for production deployments to build trust and meet compliance requirements.

​
Theme Settings

Control the visual appearance to match your brand identity. The widget automatically detects user’s system preferences and applies the appropriate theme.

​
Light and Dark Modes

Configure separate color schemes for light and dark modes. Start by configuring light mode, then add dark mode by duplicating and adjusting colors for dark backgrounds.

​
Color Configuration

Each theme has five customizable colors:
  • Brand Color: Primary accent used for buttons, links, and highlights
  • Header Background: Background for the top section of the chat window
  • Chat Background: Background for the main conversation area
  • Chat Text: Primary text color for messages and content
  • Secondary Text: Color for timestamps and less prominent text
Ensure text colors have at least 4.5:1 contrast ratio with backgrounds (WCAG AA standard). The live preview panel updates in real-time as you adjust colors.

​
Messages and Localization

Configure what users see when they first open the chat and guide them with suggestions.

​
Multi-Language Support

Frames support multiple languages simultaneously, making your AI agent accessible to global audiences. The widget automatically detects the user’s browser language and displays the appropriate messages, falling back to your primary language if their language isn’t configured. How Language Detection Works: When a visitor opens the chat widget:
  1. The widget reads the browser’s language preference (e.g., en-US, de-DE, fr-FR)
  2. It matches this against your configured languages
  3. If a match is found, it displays that language’s start message and suggestions
  4. If no match exists, it uses your first configured language (typically English)
  5. The selected language persists throughout the conversation session
This automatic detection ensures visitors always see content in their preferred language without any manual language switcher. Adding Languages: Method 1: AI Translation (Recommended) The fastest way to add multiple languages:
  1. Configure your primary language completely (start message and suggestions)
  2. Click the language selector dropdown
  3. Select Translate with AI
  4. Review AI-generated translations for 17 major languages
  5. Adjust translations to match your brand voice and cultural context
  6. Save changes
AI translation produces high-quality results but always requires review. Pay attention to:
  • Formal vs. informal tone (varies by culture)
  • Idiomatic expressions that may not translate directly
  • Brand terminology and product names
  • Cultural appropriateness of suggestions
Method 2: Manual Addition For precise control or languages not covered by AI translation:
  1. Click the language selector dropdown
  2. Select Add Language
  3. Choose from 100+ supported languages
  4. Write start message and suggestions from scratch
  5. Save changes
Use this method when you have native speakers who can create culturally appropriate content or when AI translations need significant customization. Translation Best Practices:
  1. Start with your primary language: Perfect your English (or main language) content before translating. This ensures consistent quality across all languages.
  2. Review all AI translations: AI is remarkably accurate but may miss nuances. Have native speakers review translations before deploying.
  3. Adapt, don’t just translate: Good localization considers cultural context. A suggestion like “What’s included in the Pro plan?” might work in English but need restructuring in other languages.
  4. Test with native speakers: Before going live, have team members or customers test the widget in their native language.
  5. Update all languages together: When you change suggestions based on user data, update all language versions to maintain consistency.
  6. Consider regional variations: Spanish in Spain differs from Spanish in Mexico. Use the most appropriate variant for your primary audience.
Supported Languages: The widget supports 100+ languages including:
  • Major European languages (English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, etc.)
  • Asian languages (Chinese, Japanese, Korean, Hindi, Thai, Vietnamese, etc.)
  • Middle Eastern languages (Arabic, Hebrew, Turkish, etc.)
  • Other global languages (Russian, Indonesian, Malay, Filipino, etc.)
AI translation is available for the 17 most common languages. All others can be added manually.

​
Start Message

The first message visitors see when opening the chat. Welcome users warmly, set expectations for what the AI agent can help with, and encourage engagement. Creating effective start messages:
  1. Keep it concise (2-3 sentences maximum)
  2. Mention 2-4 specific capabilities
  3. Use friendly, conversational tone
  4. End with a question to prompt response
Examples: 
Hi there! I'm here to help you find answers about [your product/service].
What can I help you with today?

Welcome! I can help with product information, account questions, technical support, and order status. What would you like to know?
Start messages that are too long get skipped. Users want to ask their question quickly - guide them but don’t overwhelm.

​
Suggested Questions

Pre-written questions users can click to start conversations instantly. Suggestions reduce friction and showcase capabilities, increasing engagement by up to 60%. Best Practices for Suggestions:
  1. Use actual customer questions - Review your support data to find common queries
  2. Keep them short - Under 50 characters per suggestion
  3. Write 3-5 suggestions - Enough variety without overwhelming
  4. Cover different topics - Balance between billing, features, technical, and general questions
  5. Update quarterly - Refresh based on what users actually ask
Good vs Poor Examples:
GoodWhyPoorWhy
”How do I reset my password?”Clear, specific, common question”Help”Too vague
”What’s included in the Pro plan?”Specific product question”I have a question about enterprise tier billing cycles”Too long
”When will my order ship?”Direct, actionable”Click here for more info”Not a question
You can generate suggestions using AI (based on your knowledge base) or write them manually. Always review AI-generated suggestions to match your brand voice.

​
Preview All Languages

Before deploying, preview how all your configured languages look:
  1. Save your frame changes
  2. Click View Preview in the Messages section
  3. See all languages side-by-side
  4. Verify translations, formatting, and suggestions
  5. Test start messages in context

​
Launcher Settings

Control where and how the chat button appears on your website.

​
Button Position

Alignment: Left or right side of the screen. Right is standard and familiar to users. Use left when right side has conflicting elements. Side Margin: Distance from screen edge. Default: 20px. Common values: 16px to 32px. Bottom Margin: Distance from screen bottom. Default: 20px. Increase to 80px+ if you have cookie banners or bottom navigation. Margin values accept any CSS unit (px, rem, em). Pixels are recommended for consistency.

​
Button Color

Customize the launcher button background color. Default matches your brand color from theme settings. Use a color that stands out but harmonizes with your site. Ensure visibility on different pages - a color that works on your homepage might not be visible on darker pages.

​
Rules - Conditional Appearance

Show different messages and behaviors based on where users are on your website. Contextual start messages can increase engagement by 2-3x compared to generic messages. Use cases:
  • Product pages: “What are the features?” or “Is this compatible with…?”
  • Pricing pages: “Which plan is right for me?” or “Can I upgrade later?”
  • Checkout pages: Disable preview popup to avoid disrupting purchase flow
  • Support section: Technical questions and billing help
  • Blog posts: Different suggestions for readers vs. customers

​
Rule Components

Each rule has three parts:
  1. URL Pattern - Which pages this rule applies to
  2. Platform - Desktop, mobile, or both
  3. Overrides - What to change (messages, preview popup setting)

​
URL Pattern Matching

Use patterns to match specific pages or sections of your site. Wildcard types:
  • * - Matches any characters except slashes (/)
  • ** - Matches any characters including slashes (/)
Common patterns:
PatternMatchesUse Case
example.com/pricingOnly pricing pageSpecific page customization
example.com/blog/*All blog posts (one level)Blog category pages
example.com/docs/**All documentation pagesEntire section
example.com/products/*/specsProduct specs pagesSpecific page type across products
**checkout**Any page with “checkout”Match across domains
Testing patterns:
  1. Create or edit a rule
  2. Click Test next to the URL pattern field
  3. Enter a pattern and test URL
  4. See normalized versions and match result
  5. Adjust pattern until it matches correctly
Normalization: Trailing slashes, query parameters (?id=123), and URL fragments (#section) are ignored during matching. This ensures consistent behavior.
Pattern examples for common scenarios: 
# Homepage only
example.com

# All product pages
example.com/products/**

# Pricing and checkout
example.com/{pricing,checkout}

# Blog posts but not blog homepage
example.com/blog/*/**

# Entire shop section
example.com/shop**

# All pages (catch-all)
**

​
Platform Targeting

Control which devices see each rule:
  • All - Desktop and mobile (default, recommended for most rules)
  • Desktop - Only users on larger screens
  • Mobile - Only users on phones and tablets
When to use platform-specific rules:
  • Mobile-only: Shorter messages, simpler suggestions (smaller screens)
  • Desktop-only: More detailed suggestions, longer explanations
  • Both: Most rules should apply to all platforms unless you have specific UX reasons
Start with “All” platforms. Only create platform-specific rules if you have data showing different user behavior or needs between desktop and mobile.

​
Rule Types

Messages Rule: Override the start message and suggestions for specific pages. Examples: “Comparing plans? I can help you choose!” (pricing page) or “Interested in [product]? I can answer questions!” (product page). Preview Rule: Enable or disable the suggestion popup for specific pages. Disable on checkout flows, forms, or video pages to avoid disruption. Enable on landing pages or complex product pages to proactively engage visitors.

​
Creating Rules

  1. Navigate to Frames → Select your frame → Rules tab
  2. Click Add Rule
  3. Choose rule type:
    • Messages Rule - Custom start message and suggestions
    • Preview Rule - Control popup behavior
  4. Configure the rule:
    • URL Pattern: Enter pattern (e.g., example.com/pricing)
    • Platform: Choose All, Desktop, or Mobile
    • Overrides: Set custom messages or toggle preview popup
  5. Test your pattern using the Test button
  6. Save changes

​
Rule Priority

When multiple rules match a page, the most specific rule wins:
  1. Exact URL matches take priority
  2. More specific wildcards beat less specific
  3. Later rules in the list override earlier ones
Example priority: 
Rule 1: example.com/**              (Least specific - applies everywhere)
Rule 2: example.com/pricing         (More specific - pricing page only)
Rule 3: example.com/pricing?plan=pro (Most specific - with query param)
On example.com/pricing?plan=pro, Rule 3 takes priority because query parameters are normalized and Rule 3 is most specific to the pricing page.
Rules are evaluated in order. If you have overlapping patterns, the last matching rule’s settings will be used. Test thoroughly to avoid unexpected behavior.

​
Rule Management

Editing rules:
  • Click the rule to expand it
  • Modify pattern, platform, or overrides
  • Changes take effect after saving the frame
Deleting rules:
  • Expand the rule
  • Scroll to the bottom
  • Click Delete Rule
  • Confirm deletion
Testing rules:
  • Use the URL pattern tester
  • Visit your website and check which messages appear
  • Use browser DevTools console to see which rule matched

​
Live Preview

The preview panel on the right side shows real-time changes as you edit: Features:
  • Updates instantly as you modify settings
  • Displays current theme (light/dark toggle)
  • Shows actual messages in selected language
  • Previews launcher button position and color
  • Interactive - test the chat flow
Using the preview:
  1. Make changes in any settings tab
  2. Watch preview update automatically
  3. Click the launcher button in preview
  4. Test start messages and suggestions
  5. Verify colors, fonts, and spacing
Keep the preview visible while editing. It’s the fastest way to catch design issues before deploying to your website.

​
Embedding Your Frame

After configuring your frame, add it to your website.

​
Getting the Embed Code

  1. Navigate to Frames
  2. Select your configured frame
  3. Click Get Embed Code (typically in the header or a dedicated tab)
  4. Copy the provided JavaScript snippet
The embed code looks like: 
<script src="https://widget.botbrains.io/embed.js"
        data-project-id="your-project-id"
        data-frame-id="your-frame-id">
</script>

​
Installation

Step 1: Paste Before </body> Add the embed code just before the closing </body> tag in your HTML: 
<!DOCTYPE html>
<html>
<head>
  <title>Your Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- botBrains Widget -->
  <script src="https://widget.botbrains.io/embed.js"
          data-project-id="your-project-id"
          data-frame-id="your-frame-id">
  </script>
</body>
</html>
Step 2: Verify Allowed Origins Ensure your website domain is listed in General Settings → Allowed Origins. Step 3: Test
  • Clear browser cache
  • Visit your website
  • Confirm the launcher button appears
  • Click to open chat
  • Verify start message and suggestions display correctly
The widget loads asynchronously and won’t block your page from rendering. Most users won’t notice any performance impact.

​
Platform-Specific Installation

For detailed integration instructions for WordPress, Shopify, React, Next.js, and other platforms, see Website Integration.

​
Testing Your Frame

Before deploying to production, test thoroughly:

​
Visual Testing

Test on desktop browsers (Chrome, Firefox, Safari, Edge), mobile devices (iOS Safari, Android Chrome), tablets, and various screen sizes (320px to 1920px+ wide). If you configured dark mode, test on dark-themed sites.

​
Functional Testing

  1. Click launcher button - chat opens
  2. Verify start message displays correctly
  3. Click suggestion - sends message
  4. Type custom message - sends and receives response
  5. Upload image (if enabled) - processes correctly
  6. Open/close multiple times - state persists
  7. Refresh page - conversation history retained
  8. Visit different pages - correct rules apply

​
Troubleshooting

​
Widget Not Appearing

  1. Verify embed code is before </body> tag
  2. Check Project ID and Frame ID are correct
  3. Ensure website domain is in Allowed Origins
  4. Confirm frame is saved
  5. Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
  6. Open DevTools (F12) and check Console for CORS errors

​
Wrong Start Message Showing

URL pattern rule likely isn’t matching correctly. Use the pattern tester to verify pattern matches your URL, check rule priority (more specific rules should come later), verify correct language is selected, and clear browser cache.

​
Colors Not Updating

Save changes, clear browser cache completely, check you’re editing the correct theme (light vs dark), verify changes in live preview panel first, or try incognito mode to bypass cache.

​
Rules Not Applying

Open browser console and look for [botBrains] debug messages showing matched rules. Verify URL pattern using built-in tester, check platform targeting (desktop vs mobile), and confirm frame was saved.

​
Performance Issues

If widget slows down page: compress assistant and header images, verify embed code has async attribute, check for conflicts with other scripts, minimize number of rules, or contact support.

​
Mobile Display Issues

Adjust bottom/side margins to avoid overlapping mobile navigation, test on real devices (not just browser emulation), verify viewport meta tag exists, and check for CSS conflicts.

​
Best Practices

​
Design

  1. Start simple: Begin with default settings and customize gradually
  2. Brand consistency: Match your website’s color palette and design language
  3. Readability first: Test contrast rigorously - ensure text is easily readable

​
Content

  1. Clarity over cleverness: Start messages should immediately clarify what the AI agent can do
  2. Update suggestions quarterly: Review conversation data and update suggestions to match actual user questions
  3. Context matters: Use rules for different messages on product, pricing, and support pages

​
Technical

  1. Test thoroughly: Test on real devices, not just browser simulations
  2. Monitor performance: Use Google PageSpeed Insights before and after adding the widget
  3. Test in staging first: Create a duplicate frame for testing major changes before updating production
Never edit live production frames directly. Always test changes in staging environment first.

​
Accessibility

  1. Keyboard navigation: Widget supports Tab to launcher button, Enter to activate
  2. Screen reader friendly: Widget includes ARIA labels - don’t override with custom CSS
  3. Color contrast: Maintain WCAG AA standard (4.5:1 ratio) for all text

​
Advanced Usage

​
Multiple Frames

Create separate frames for different brands, environments (staging/production), A/B testing, or regional variations. Navigate to Frames, click Create New Frame, configure independently, and use different frame IDs in embed codes.

​
Programmatic Control

The Web SDK allows programmatic control of the widget via JavaScript. You can open/close the chat, send messages programmatically, and listen for events. This enables use cases like opening chat from custom buttons, pre-filling messages from links, tracking engagement in analytics, and A/B testing different frame configurations. For complete Web SDK documentation and embed details, see Website Integration.

​
Next Steps

Now that you understand frames:

Deploy to Production

Install the widget on your website with platform-specific instructions

Configure Deployments

Connect frames to AI versions and manage releases

Monitor Conversations

See how visitors interact with your widget and identify improvements

Analyze Engagement

Track widget performance metrics and conversation quality
 Your chat widget is the primary way customers interact with your AI. Invest time in designing a frame that represents your brand well and guides users effectively - the engagement improvements will be measurable and significant.