Configuring Your Chatbot Widget¶

Learn how to customize and configure your chatbot widget to match your brand and website requirements.

What You'll Achieve¶

By the end of this guide, you'll have:

A fully customized chatbot widget matching your brand identity
A secure authentication token protecting your widget from unauthorized use
The install code ready to embed on your website
Domain restrictions configured (optional) to control where your widget can be used

The Goal: Get your chatbot widget installed and running on your website with the right branding, security, and functionality for your users.

Overview¶

The widget configuration page provides seven key sections to customize your chatbot's appearance, behavior, security, and deployment. Each tab controls different aspects of your widget.

Basic Settings¶

Configure the fundamental properties of your chatbot widget.

Give your widget a descriptive name for internal identification and management.

Naming Convention

Use a clear, descriptive name like "Customer Support Chat" or "Sales Assistant" to easily identify the widget in your dashboard.

Add an optional description to document the widget's purpose and usage.

Avatar Image¶

Upload a custom avatar image that represents your chatbot (max 1MB).

Recommended Specifications

Format: PNG, JPG, or WebP
Size: 512x512 pixels
File size: Under 1MB
Transparent backgrounds work best

Appearance & Branding¶

Customize colors, icons, and visual elements to match your brand identity.

Preset Themes¶

Choose from pre-designed color palettes or create your own custom theme:

Professional Blue - Corporate and trustworthy
Warm Orange - Friendly and approachable
Modern Purple - Creative and innovative
Fresh Green - Natural and calming
Classic Black - Elegant and sophisticated

Custom Colors¶

Fine-tune individual color elements:

Primary Color - Main accent color for buttons and active states
Secondary Color - Supporting UI elements
Text Color - Chat message text
Background Color - Widget background

Color Contrast

Ensure sufficient contrast between text and background colors for accessibility (WCAG AA compliance recommended).

Icon Settings¶

Customize the widget's icon appearance:

Upload custom icon image
Adjust icon size and style
Configure hover effects

Layout & Position¶

Control where and how the widget appears on your website.

Choose the display format:

Popup - Expandable chat window (recommended)
Embedded - Inline widget within page content
Full Page - Dedicated chat page

Position Settings¶

Configure widget placement:

Bottom Right (default) - Most common, non-intrusive
Bottom Left - Alternative corner placement
Custom - Specify exact pixel position

Display Behavior¶

Control when and how the widget appears:

Auto-open on page load
Delay before showing
Show on specific pages only
Mobile vs desktop visibility

Content & Messages¶

Customize the conversational experience.

Welcome Message¶

Set the initial greeting message users see when opening the chat.

Example:

👋 Hello! How can I help you today?

Example Questions¶

Add suggested questions to help users get started:

"What can you help me with?"
"How do I get started?"
"Tell me more about your services"

Best Practices

Keep questions clear and specific
Align with common user needs
Update based on analytics and feedback

Placeholder Text¶

Customize the input field placeholder (e.g., "Type your message here...")

Authentication¶

Secure your widget with token-based authentication.

Generate Authentication Token¶

Click Generate Token Now to create a unique authentication token
Store the token securely (environment variables recommended)
Use this token when embedding the widget on your website

Security Best Practices

Never commit tokens to Git or share publicly
Store in environment variables, not source code
Regenerate immediately if token is compromised
Each widget should have its own unique token

Token Status Indicators¶

✓ Token Configured (Green) - Widget is secured and ready
⚠️ No Token Configured (Red) - Widget cannot authenticate

Regenerate Token¶

Click Regenerate Token if you need to:

Replace a compromised token
Update security credentials
Reset authentication

Token Regeneration Impact

Regenerating a token will immediately invalidate the old token. Update all websites using the widget to prevent authentication failures.

Allowed Domains¶

Control which websites can embed your widget (optional but recommended).

Domain Restriction¶

Add specific domains to create a whitelist of approved websites:

example.com
www.example.com
app.example.com

Domain Format

Enter domains without http:// or https://
Subdomains must be listed separately
Use * for wildcard (not recommended for security)

Why Restrict Domains?¶

Benefits: - Prevent unauthorized use of your widget - Protect API quota and credits - Control brand representation - Reduce spam and abuse

When to Use: - Production websites with fixed domains - Multiple sites under your control - Public-facing deployments

When to Skip: - Development and testing - Localhost environments - Internal tools

Managing Domains¶

Add Domain - Click "Add" to include new domain
Remove Domain - Click trash icon to revoke access
No Restrictions - Leave empty to allow any domain (development only)

Install Code¶

Get the embed code to add your chatbot to your website.

Platform-Specific Instructions¶

HTMLReactVueWordPressWordPress Plugin

Copy and paste this code before the closing </body> tag:

<script 
    src="https://cdn.brilio.ai/embed.js" 
    widget-uuid="your-widget-uuid" 
    widget-token="PLACE_YOUR_TOKEN_HERE"
    async
></script>

Add to your React component:

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://cdn.brilio.ai/embed.js';
    script.setAttribute('widget-uuid', 'your-widget-uuid');
    script.setAttribute('widget-token', 'PLACE_YOUR_TOKEN_HERE');
    script.async = true;
    document.body.appendChild(script);

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

  return <div>Your App</div>;
}

Add to your Vue component:

<template>
  <div>Your App</div>
</template>

<script>
export default {
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://cdn.brilio.ai/embed.js';
    script.setAttribute('widget-uuid', 'your-widget-uuid');
    script.setAttribute('widget-token', 'PLACE_YOUR_TOKEN_HERE');
    script.async = true;
    document.body.appendChild(script);
  }
}
</script>

Add to your theme's footer.php or use a plugin like "Insert Headers and Footers":

<script 
    src="https://cdn.brilio.ai/embed.js" 
    widget-uuid="your-widget-uuid" 
    widget-token="PLACE_YOUR_TOKEN_HERE"
    async
></script>

Download the Brilio WordPress plugin
Upload to your WordPress site (Plugins → Add New → Upload)
Activate the plugin
Go to Settings → Brilio Chat
Enter your widget UUID and token
Save settings

Replace Placeholder

Don't forget: Replace PLACE_YOUR_TOKEN_HERE with your actual authentication token from the Authentication tab.

Installation Steps¶

Copy the embed code for your platform
Replace the token placeholder with your actual token
Paste into your website (preferably before closing </body> tag)
Test the widget on your website
Verify authentication - Check browser console for errors

Troubleshooting¶

Widget not appearing?

✓ Check that the script is loaded (view page source)
✓ Verify the widget UUID is correct
✓ Confirm the token is valid (check Authentication tab)
✓ Check browser console for JavaScript errors
✓ Ensure domain is in allowed list (if configured)

Authentication errors?

Token missing or incorrect → Update with valid token
Domain blocked → Add domain to Allowed Domains tab
Token expired → Regenerate token in Authentication tab

Before going live, test your widget thoroughly:

Checklist¶

Widget appears on page load
Avatar and branding match your design
Welcome message displays correctly
Example questions are clickable and working
Chat conversations function properly
Widget position looks good on mobile and desktop
Authentication token is working
Domain restrictions are enforced (if configured)

Testing Tools¶

Browser DevTools - Check console for errors
Mobile Testing - Test on actual mobile devices
Cross-Browser - Test in Chrome, Safari, Firefox, Edge
Network Tab - Verify API calls are successful

Best Practices¶

Design¶

Use brand colors consistently
Ensure readability with proper contrast
Test on multiple screen sizes
Keep welcome message concise and friendly

Security¶

Always use authentication tokens
Configure domain restrictions for production
Store tokens in environment variables
Rotate tokens periodically
Monitor for unauthorized usage

Performance¶

Use async script loading (default)
Minimize custom styling overhead
Monitor widget load times
Optimize avatar image size

Content¶

Write clear, helpful welcome messages
Provide relevant example questions
Update content based on user feedback
Align messaging with brand voice

Common Issues¶

Cause: Script blocked, incorrect UUID, network error

Solution: 1. Check browser console for errors 2. Verify script URL is correct 3. Test in incognito mode (avoid browser extensions) 4. Check network tab for failed requests

Authentication failures¶

Cause: Missing/invalid token, domain restriction

Solution: 1. Verify token is correctly placed in embed code 2. Check Authentication tab for valid token 3. Ensure domain is in Allowed Domains list 4. Regenerate token if compromised

Styling conflicts¶

Cause: CSS conflicts with your website

Solution: 1. Widget uses scoped styles to minimize conflicts 2. Check for CSS specificity issues 3. Use browser DevTools to inspect styles 4. Contact support if issues persist

Next Steps¶

What is an Agent? - Understand agent capabilities
Getting Started with Agents - Create your first agent
Why Knowledge Matters - Improve agent responses

Need help? Contact support at support@brilio.ai