Skip to main content
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

Each frame has five configuration sections:
SectionWhat you configure
GeneralAssistant name and images, security (allowed origins, whitelisted IPs), features (image upload, preview popup)
ThemeLight and dark mode colors
MessagesStart message and suggested questions per language
LauncherButton position, spacing, and color
RulesURL 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
Frame editor interface showing tabs for General, Theme, Messages, Launcher, and Rules with live preview panel on the right

​
General Settings

​
Assistant Identity

Configure how your AI agent presents itself to visitors.
SettingPurposeFormat/Requirements
Assistant NameDisplayed in conversation headersAny text (for example, “Support Bot,” “Emma”)
Assistant ImageAvatar next to AI messagesPNG/JPEG/SVG/WebP, 64x64px+, autocompressed 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. The system scans and validates images 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 (for example, 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 (for example, en-US, de-DE, fr-FR)
  2. It matches this against your configured languages
  3. If it finds a match, 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 covers the 17 most common languages. You can add all others manually.

​
Start Message

The first message visitors see when opening the chat. Welcome users, 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
Language dropdown showing multiple configured languages with AI translation option, and preview panel displaying start message and suggestions in different languages

​
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). We recommend px 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 my setup?”
  • 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 (for example, 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
Rules tab showing a list of configured rules with URL patterns, platform targeting (All/Desktop/Mobile), and a rule editor form with pattern tester showing match results

​
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 the system normalizes query parameters 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.

​
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 readable at all sizes

​
Content

  1. Clarity over cleverness: Start message + suggestions 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

​
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

Deployment Versioning

Connect frames to AI versions and manage releases
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 to the right answers - the engagement improvements will be measurable and significant.