The AI Webchat widget is a powerful, embeddable chat interface that can be integrated into any website. It provides a seamless user experience with customizable themes, positions, and security features.
💡 What you'll get: A fully functional AI chat widget that can be embedded on your website with just a few lines of code. The widget is responsive, secure, and customizable.
Key Features
✅ Easy integration with a single script tag or iframe
✅ Responsive design (mobile-friendly)
✅ Customizable themes and positions
✅ Secure token-based authentication
✅ Origin-based security (CORS protection)
✅ Programmatic API for control (open, close, toggle)
✅ Resizable widget - users can adjust the chat size
✅ Draggable widget - users can move the chat around
✅ Close button - users can close the chat widget
2. Prerequisites
Before you begin, ensure you have the following information from your AI Buddy dashboard:
1Agent ID - A unique identifier for your AI agent (UUID format)
2Embed Token - A secure JWT token for authenticating the widget
3Backend URL - The base URL of the AI Buddy backend service
⚠️ Important: Your domain must be added to the "Allowed Domains" list in the AI Buddy dashboard before the widget will work. Contact your administrator if you need to add your domain.
3. Integration Steps
Step 1: Add the Embed Script
Add the following script tag to your HTML page, typically in the <head> section or just before the closing </body> tag:
After the widget is loaded, you can control it programmatically:
// Open the chat widget
window.AIBuddyWidget?.open();
// Close the chat widget
window.AIBuddyWidget?.close();
// Toggle the chat widget
window.AIBuddyWidget?.toggle();
// Send a message programmatically
window.AIBuddyWidget?.sendMessage('Hello!');
Listening to Widget Events (iframe only)
If you're using an iframe, you can listen to events from the widget:
// Listen for messages from the embed widget
window.addEventListener('message', function(event) {{
// Security: In production, validate event.origin
if (event.data && event.data.type) {{
switch(event.data.type) {{
case 'aibuddy:close':
// Widget was closed by user
console.log('Widget closed');
// Hide iframe if needed
document.getElementById('chat-iframe').style.display = 'none';
break;
case 'aibuddy:resize':
// Widget was resized by user
console.log('Widget resized:', event.data.data);
// event.data.data contains: {{ width, height }}
break;
case 'aibuddy:move':
// Widget was moved by user
console.log('Widget moved:', event.data.data);
// event.data.data contains: {{ x, y }}
break;
case 'aibuddy:ready':
// Widget is ready
console.log('Widget ready:', event.data.data);
break;
}}
}}
}});
5. Testing Your Integration
🧪 Test Configuration
Token can also be passed as URL parameter: ?token=YOUR_TOKEN
6. Troubleshooting
❌ Error: "Origin is not allowed"
Problem: Your domain is not in the allowed origins list.
Solution:
Contact your administrator to add your domain to the "Allowed Domains" list in the AI Buddy dashboard
Ensure you're using the exact domain (including protocol: https:// or http://)
For subdomains, you may need to add each subdomain separately or use a wildcard pattern (e.g., *.example.com)
❌ Error: "Missing required 'token' parameter"
Problem: The embed token is missing or invalid.
Solution:
Verify that the token parameter is included in the script URL
Check that the token hasn't expired (tokens typically expire after a set period)
Generate a new embed token from the AI Buddy dashboard
Ensure the token is URL-encoded if it contains special characters
❌ Error: CORS policy blocked
Problem: The browser is blocking the request due to CORS (Cross-Origin Resource Sharing) policy.
Solution:
Verify your domain is in the allowed origins list
Check that you're using HTTPS (required for production)
Ensure the backend URL is correct and accessible
Check browser console (F12) for detailed CORS error messages
❌ Widget not appearing
Problem: The chat widget doesn't show up on your page.
Solution:
Check browser console (F12) for JavaScript errors
Verify the script tag is correctly placed and the URL is valid
Ensure no other scripts are blocking the widget initialization
Check that your page has loaded completely (try placing the script before </body>)
Test with the "Show Chat Widget" button above to verify your configuration
❌ Mixed Content Error (HTTPS/HTTP)
Problem: Your page is served over HTTPS but trying to load the widget from HTTP (or vice versa).
Solution:
Ensure both your website and the backend URL use the same protocol (preferably HTTPS)
If your site is HTTPS, the backend URL must also be HTTPS
Update the backend URL in your script tag to use HTTPS
❌ Widget appears but chat doesn't work
Problem: The widget UI loads but messages aren't being sent or received.
Solution:
Check browser console (F12) for network errors
Verify the Agent ID is correct
Ensure the backend API is accessible and responding
Check that WebSocket connections are allowed (if used for real-time chat)
Verify firewall/proxy settings aren't blocking API requests
7. Best Practices
Security
✅ Always use HTTPS in production environments
✅ Keep your embed token secure and don't expose it in client-side code if possible
✅ Regularly rotate your embed tokens
✅ Only add trusted domains to the allowed origins list
Performance
✅ Load the widget script asynchronously (place before </body>)
✅ Consider lazy-loading the widget (load only when user interacts)
✅ Monitor widget load times and optimize if necessary
User Experience
✅ Choose an appropriate position that doesn't obstruct important content
✅ Test the widget on mobile devices to ensure responsiveness
✅ Consider the theme that best matches your website design
✅ Provide clear instructions to users on how to use the chat
Testing
✅ Test on multiple browsers (Chrome, Firefox, Safari, Edge)
✅ Test on different devices (desktop, tablet, mobile)
✅ Verify functionality in both development and production environments
✅ Test with different network conditions
✅ Integration Complete! If you've followed all steps and your widget is working, congratulations! If you're experiencing issues, refer to the Troubleshooting section above or contact support.