Chat Widgets

Overview

Chat widgets are embeddable chat interfaces that you can add to your website. When visitors use the chat widget, their messages come directly into brayv.ai Conversations and are handled by your default global AI agent. Chat widgets collect their phone number and a message, and then lets the contact know they will receive a text message. Your Global default text ai agent (if configured: Settings > Text AI) responds to their message via SMS.

Chat widgets are perfect for:

• Website visitor engagement
• Real-time lead capture
• Initiating conversations that continue via SMS
• Providing instant responses on your website
• Qualifying leads before they leave your site

Important: Chat widgets don't have journey enrollment configuration. Conversations start with your default global AI agent, which can add contacts to journeys using conditional tools when appropriate, and can also just answer general customer service questions based on the instructions you give it and info in your knowledge base.

Creating a Chat Widget

Step 1: Go to Settings > Lead Sources

Step 2: Click "Create New" and select "Chat Widget"

Step 3: Configure widget settings (detailed below)

Step 4: Click "Create Chat Widget"

Step 5: Copy the embed code and add to your website

Chat Widget Configuration

Basic Settings

Name (Required)

• Internal name for the widget
• Not visible to website visitors
• Example: "Main Website Chat", "Landing Page Widget"

Text Customization

Bubble Text

• Text shown on the floating chat button/bubble
• Default: "Text us here!"
• Customize: "Chat with us!", "Need help?", "Get a quote!"
• Keep it short (2-4 words works best)

Header Text

• Text shown at the top of the opened chat window
• Default: "Send us a message"
• Customize: "How can we help?", "Let's chat", "Get in touch"

Instructions

• Helpful text shown in the chat window
• Default: "Enter your info here and a quick message, and we'll text you back right away!"
• Customize to set expectations
• Example: "Share your name, phone number, and question - we'll text you right back!"

Placeholder Text

• Placeholder in the message input field
• Default: "Type your message here..."
• Customize: "What can we help with?", "Your question..."

Submit Button Text

• Text on the send button
• Default: "Send Message"
• Customize: "Send", "Chat Now", "Let's Talk"

Success Message

• Message shown after successful submission
• Default: "Thanks for your message! We'll get back to you soon."
• Customize: "Got it! We'll text you shortly.", "Thanks! Check your phone for our message."

Required Information Collection

The chat widget automatically collects:

• First Name - Required
• Phone Number - Required for AI to continue conversation via SMS
• Initial Message - What the visitor wants to talk about

Note: These fields are not configurable - they're essential for the widget to function properly.

Opt-In Settings

Enable Opt-In

• Toggle to show/hide SMS opt-in checkbox
• Highly Recommended - Should always be enabled for compliance

Opt-In Required

• Make the opt-in checkbox required before submission
• Highly Recommended - Ensures SMS compliance

Opt-In Text

• Customizable compliance text
• Default provided automatically from your account settings
• Good opt-in example text: "By submitting my phone number I agree to receive calls and or text messages from (insert your business name). Carrier message and data rates may apply. Calls may include AI or machine generated voices. Message frequency varies."

Why Opt-Ins Matter:

• Required for SMS compliance regulations
• Protects your business
• Sets proper expectations with visitors
• Always use opt-ins for chat widgets that are external, i.e. on your public website

Bot Protection (Cloudflare Turnstile)

Enable Turnstile

• Toggle to enable Cloudflare Turnstile bot protection
• Adds invisible or minimal challenge to prevent spam
• Free protection from bots and automated spam

When to Use:

• Public-facing websites
• High-traffic sites
• If experiencing spam chat submissions

When to Skip:

• Internal sites
• Sites with very low traffic
• Behind authentication

Setup: Enabling Turnstile requires Cloudflare configuration in your account settings. Contact support if you need help.

Styling

Primary Color

• Main color for widget elements (header, send button)
• Defaults to your account's brand color
• Enter hex color code (e.g., #3B82F6)

Secondary Color

• Accent color for secondary elements
• Defaults to complement primary color
• Enter hex color code (e.g., #10B981)

Widget Logo URL (Optional)

• Custom logo shown in widget header
• Provide full URL to logo image
• If not provided, uses your account logo
• Recommended size: 40x40 to 200x200 pixels
• Example: https://yourdomain.com/logo.png

Active/Inactive Toggle

Active

• Widget is live and accepts messages
• Visitors can start conversations

Inactive

• Widget is disabled
• Useful for temporarily disabling without removing embed code
• Visitors won't see the widget on your site

Embedding Your Chat Widget

After creating the widget, embed it on your website.

Getting the Embed Code

Step 1: Open your chat widget in Lead Sources

Step 2: Go to the "Embed" tab

Step 3: Copy the embed code provided

Example Embed Code Format (do not copy this):

<script>
  (function() {
    var script = document.createElement('script');
    script.src = 'https://cdn.brayv.ai/chat-widget.js';
    script.setAttribute('data-widget-id', '[WIDGET_ID]');
    script.async = true;
    document.body.appendChild(script);
  })();
</script>

Installing on Your Website

Where to Place: Add the embed code before the closing </body> tag of your website.

For Most Websites:

1. Access your website's HTML
2. Find the </body> tag (usually in footer or layout template)
3. Paste embed code just before </body>
4. Save and publish

Platform-Specific Instructions:

WordPress:

1. Go to Appearance > Theme Editor (or use plugin like "Insert Headers and Footers")
2. Add code to footer.php before </body>
3. Or use a plugin like "Custom HTML" widget in footer

Squarespace:

1. Go to Settings > Advanced > Code Injection
2. Paste code in "Footer" section
3. Save

Wix:

1. Go to Settings > Custom Code
2. Add new code
3. Paste embed code
4. Set to load on "All Pages" and "Body - end"
5. Apply

Shopify:

1. Online Store > Themes > Actions > Edit Code
2. Open theme.liquid
3. Paste before </body> tag
4. Save

Webflow:

1. Project Settings > Custom Code
2. Paste in "Footer Code" section
3. Publish site

Custom/HTML Websites:

1. Open your HTML file
2. Find </body> tag
3. Paste embed code before it
4. Upload file to server

Widget Appearance

Default Position:

• Bottom right corner of screen
• Floating above content
• Collapses to small bubble
• Expands when clicked

Mobile Responsive:

• Automatically adapts to mobile screens
• Full-screen when opened on small devices
• Touch-optimized

How Chat Widgets Work

User Flow

1. Visitor sees chat bubble on your website
2. Clicks bubble to open chat window
3. Sees instructions and form fields
4. Enters name, phone, and message
5. Checks opt-in box (if required)
6. Clicks send
7. Sees success message
8. Receives text message response from AI agent (if default global agent configured in Settings > Text AI)

System Flow

1. User submits chat widget
2. Contact created or updated (matched by phone)
3. Message appears in Conversations (like an incoming SMS)
4. Default global AI agent receives the message (if default global agent configured in Settings > Text AI)
5. AI agent responds via SMS to the phone number provided
6. Conversation continues via text messaging
7. AI can add contact to journey using conditional tools if appropriate, or send you notifications based on certain things the contact is interested in etc. (configure by adding a conditional tool with an action)

Contact Matching

If phone number matches existing contact:

• Contact is updated
• Message added to conversation history

If phone number doesn't match:

• New contact is created
• All fields saved
• New conversation started

Note: Matching is by phone number only.

Integration with AI Agents

Chat widgets do NOT have direct journey assignment.

Instead:

1. Messages go to your default global AI agent (Settings > Text AI)
2. Global agent responds and engages
3. Global agent can use conditional tools to add to journeys
4. Once added to journey, journey AI agent takes over

Example Flow:

Visitor submits chat widget: "I need HVAC repair"
    ↓
Default global AI agent receives message
    ↓
AI responds: "Hi! I'd be happy to help. Can you tell me more about the issue?"
    ↓
User responds with details
    ↓
AI conditional tool triggers: "user indicates HVAC need"
    ↓
Contact added to HVAC Journey
    ↓
HVAC Journey AI agent takes over conversation

Chat Widget vs Forms vs Webhooks

When to Use Chat Widgets

Best For:

• Conversational lead capture
• Instant engagement
• Continuing conversation via SMS
• Building rapport before phone number collection
• Easy acccess customer support for your customers

Advantages:

• Low friction
• Higher engagement rates
• Immediate AI response
• Continues seamlessly to SMS
• Not tied to any specific request type

When to Use Forms Instead

Better For:

• Specific information collection
• Complex data requirements
• Direct journey enrollment
• Landing pages with specific goals

When to Use Webhooks Instead

Better For:

• Third-party integrations
• Automated lead sources
• External systems
• Custom workflows

Best Practices

Configure Your Default Global Agent

Since chat widgets use your default global agent:

1. Ensure global agent is configured (Settings > Text AI)
2. Add conditional tools for actions you want taken on common requests
3. Include "Add to Journey" tools for different scenarios
4. Test the agent thoroughly
5. Ensure you add relevant FAQs to AI knowledge base

Example Global Agent Tools:

• "User mentions HVAC" → Add to HVAC Journey
• "User mentions plumbing" → Add to Plumbing Journey
• "User mentions emergency" → Send Jake Smith email notification

Always Enable Opt-Ins

For SMS Compliance:

• Enable SMS opt-in
• Make it required
• Use default compliant text
• This protects your business

Set Clear Expectations

In Instructions Text:

• Tell visitors they'll receive a text message
• Set response time expectations
• Example: "We'll text you back within 2 minutes!" (only do this if you are allowing the AI to respond to these messages)

Keep Bubble Text Short

Best Bubble Text:

• "Chat with us!"
• "Text us here"
• "Need help?"
• "Get a quote"

Avoid:

• Long sentences
• Multiple lines
• Detailed instructions (save for the opened window)

Match Your Brand Colors

• Set primary color to your brand color
• Ensures widget looks native to your site
• Better conversion rates

Test Before Going Live

Testing Checklist:

1. Submit a test chat from your website
2. Verify message appears in Conversations
3. Confirm AI agent responds
4. Check contact was created correctly
5. Test on mobile devices
6. Verify styling looks good on your site

Monitor Chat Widget Performance

Track:

• Number of chat submissions
• Conversion to booked appointments
• Response times
• Common questions/requests

Optimize Based On:

• Which messages the AI handles well
• What causes confusion (add FAQs to knowledge base or additional instructions for agent)
• Common journey add triggers

Use Custom Logo for Multiple Sites

If you have multiple websites or brands:

• Create separate widgets
• Use different logos for each
• Customize colors to match each site
• Track performance separately

Troubleshooting

Problem: Widget not appearing on website

Solution:

• Verify embed code is correctly placed before </body> tag
• Clear browser cache and hard refresh (Cmd+Shift+R or Ctrl+Shift+F5)
• Check widget is set to "Active" in brayv.ai
• Verify embed code wasn't modified
• Check browser console for JavaScript errors
• Ensure your website allows external scripts

Problem: Messages not appearing in Conversations

Solution:

• Verify widget is active
• Check that user submitted with valid phone number
• Review Chat Widget history for errors
• Verify default global AI agent is configured
• Check account has text messaging enabled

Problem: AI not responding to chat messages

Solution:

• Verify default global AI agent is set (Settings > Text AI)
• Verify new contacts default to AI enabled (Settings > Text AI)
• Check that AI agent has instructions configured
• Ensure account has active phone number and A2P approved
• Verify contact has text AI enabled
• Check AI Text Agent Logs for errors

Problem: Opt-in checkbox not showing

Solution:

• Verify "Enable Opt-In" is toggled on
• Save widget settings again
• Clear cache and test again
• Check that opt-in text is configured

Problem: Widget styling looks wrong

Solution:

• Adjust primary and secondary colors
• Check that logo URL is valid and accessible
• Test on different browsers
• Verify colors are in hex format (#RRGGBB)
• Try clearing custom logo to use default

Problem: Getting spam submissions

Solution:

• Enable Cloudflare Turnstile bot protection
• Make opt-in required (adds friction)
• Monitor submission patterns
• Turn off AI and enable Do Not Text for repeat offender phone numbers

Problem: Widget conflicts with site design

Solution:

• Adjust colors to match site better
• Ensure widget doesn't cover important site elements
• Test on mobile and desktop

Problem: Contact created without phone number

Solution:

• Phone is required field - should not be possible
• Verify widget configuration
• Check widget version (may need update)
• Contact support if issue persists

Advanced Tips

Multiple Widgets for Different Pages

Create separate widgets for:

• Different products/services
• Different traffic sources
• A/B testing different messaging

Benefits:

• Track performance by page
• Customize messaging per audience
• Better analytics

Coordinate with Global Agent

Design your global agent with chat widgets in mind:

In Agent Configuration and Knowledge:

• Include knowledge for website-specific questions (ie, "what page can i find your photos of previous projects on?" Add an FAQ to knowledgebase with a link to your gallery page)
• Have tools and instructions ready for common chat widget requests (ie, Conditional Tool: trigger condition: "the user indicates they need service on their water treatment system". Action: send email notification to Joe Smith. In the Agent instructions, goals section: "if the user indicates they need service on their water treatment system, tell them you will notify the team and someone will contact them shortly.")

Track Lead Source

All chat widget contacts have:

• Source automatically set
• Can filter by chat widget source
• Track conversion rates
• Compare to other lead sources in dashboard (opportunities only created when added to a journey)

Related Features

• AI Text Agents - Configure the global agent that handles chat
• Managing Contacts - View contacts from chat widget
• Forms - Alternative lead capture method