Skip to main content
The JavaScript embed script is perfect for web applications that need rich chat functionality with minimal setup. Add a powerful AI chatbot to your website in minutes.

​
What You Can Do

  • Simple embed - Add a chat widget to your website in minutes
  • Identity verification - Add advanced capabilities and customizations to your agent, by leveraging contacts and actions
  • Widget control - Programmatically open/close the chat interface
  • Event listeners - React to user messages and AI responses
  • Actions - Create interactive forms and actions directly in the chat interface
  • Dynamic content - Show personalized initial messages

​
Quick Start Guide

1

Get Your Embed Script

  1. Go to your Chatbase Dashboard
  2. Select your AI Agent → Deploy → click on manage on Chat widget → select Embed tab
  3. Copy the JavaScript embed script
Deploy embed tab
2

Add to Your Website

Paste the code in your website’s <head> section or before the closing </body> tag.
Place in <head> for faster loading, or before </body> if you have loading performance concerns.
3

Test Integration

Visit your website and look for the chat bubble. Click it to test!
Your AI Agent should respond based on your training data.
4

Add Advanced Features (Optional)

Enhance your integration with identity verification, custom events, or styling.
// Example: Listen for user messages
window.chatbase.addEventListener("user-message", (event) => {
  console.log("User said:", event.content);
  // Your custom logic here
});

​
JavaScript Embed Core Features

  • Identity Verification
  • Event Listeners
  • Widget Control
  • Client-Side Custom Actions
Secure user sessions with verified identitiesPerfect for authenticated applications where you need to:
  • Verify user identity for actions
  • Pass user context (name, email, etc.) to AI Agent
  • Use data stored in contacts to perform actions.
Full Identity Verification Guide →

​
Best Practices

​
Performance Optimization

Load the embed script asynchronously to avoid blocking your page load. The provided embed code already handles this automatically.
<!-- The embed script loads asynchronously by default -->
<script>
// Your embed code here - it won't block page rendering
</script>

​
User Experience

  • Test the chat widget on various mobile devices
  • Ensure the chat bubble doesn’t interfere with mobile navigation
  • Consider using smaller initial messages on mobile screens
  • The widget includes ARIA labels and keyboard navigation
  • Ensure sufficient color contrast in custom styling
  • Test with screen readers for accessibility compliance
  • Pass relevant page/user context to provide better responses
  • Use identity verification for personalized experiences
  • Clear chat context when users navigate to different sections

​
Security Considerations

Never expose sensitive data through the embed script. Use identity verification instead of passing raw user data.

​
Troubleshooting

  1. Check that your agent ID is correct in the embed script
  2. Verify the script is placed correctly in your HTML
  3. Check browser console for JavaScript errors
  4. Ensure your website domain is allowed in agent settings
  1. Ensure event listeners are added after the chatbase script loads
  2. Check that event names are spelled correctly
  3. Verify the chatbase object is properly initialized
  4. Use browser dev tools to debug event flow

​
What’s Next?

Identity Verification

Secure your chatbot for authenticated users

REST API Integration

Integrate Chatbase with your existing backend

Client-Side Custom Actions

Call backend actions from the client side

Client-Side Custom Forms

Add interactive forms and data collection to your chat
⌘I