Skip to main content
Event listeners allow you to monitor and react to everything happening in your AI Agent conversations. From user messages to custom actions, you can build rich, interactive experiences that respond dynamically to user interactions.

​
Why Use Event Listeners?

Create dynamic, responsive interactions:
  • Show contextual information based on conversation topic
  • Trigger UI changes based on user messages
  • Provide visual feedback for AI responses
  • Integrate chat with other page elements
Connect your chat with external systems:
  • Send data to CRM or analytics platforms
  • Trigger email campaigns or notifications
  • Update user profiles or preferences
  • Sync conversation data with support systems

​
Prerequisites

A website with the Chatbase embed script already installed and working. New to Chatbase? Check out Your First Agent to get started with the embed script first.

​
Available Events

Listen for these events to monitor and respond to chat activity:
  • Message Events
  • Action Events
Track conversation flow
​
user-message
event
Triggered when a user sends a messagePayload: { data: { content: string }, type: "user-message" }
Use cases: Analytics, message validation, auto-suggestions
​
assistant-message
event
Triggered when your AI Agent respondsPayload: { data: { content: string }, type: "assistant-message" }
Use cases: UI updates, satisfaction surveys, follow-up actions
// Example: Track conversation topics
window.chatbase.addEventListener('user-message', (event) => {
  console.log('User asked:', event.data.content);
  
  // Track in analytics
  analytics.track('Chat Message Sent', {
    message_length: event.data.content.length,
    timestamp: new Date().toISOString()
  });
});

window.chatbase.addEventListener('assistant-message', (event) => {
  console.log('AI responded:', event.data.content);
  
  // Show satisfaction survey after response
  if (event.data.content.includes('solution') || event.data.content.includes('help')) {
    showSatisfactionSurvey();
  }
});

​
Basic Event Listener Usage

​
Adding Event Listeners

Add event listeners using the simple syntax: 
window.chatbase.addEventListener(eventName, callbackFunction);
​
eventName
enum
required
Must be one of the event names listed in Available Event Types.
​
callback
function
required
Function to be called when the event is fired. The event payload is passed as an argument.

​
Removing Event Listeners

Remove listeners when they’re no longer needed to prevent memory leaks: 
// Store reference to callback function
const myEventHandler = (event) => {
  console.log('Event received:', event);
};

// Add listener
window.chatbase.addEventListener('user-message', myEventHandler);

// Remove listener later
window.chatbase.removeEventListener('user-message', myEventHandler);

​
Event Management Best Practices

​
Troubleshooting

Problem: Event listeners aren’t being calledSolutions:
  • Check script loading: Verify that the Chatbase embed script has loaded completely before adding event listeners. The window.chatbase object should be available.
  • Verify event names: Double-check that you’re using the correct event names. Valid events include: user-message, assistant-message, tool-call, and tool-result. Typos in event names will prevent listeners from firing.
  • Check browser console: Look for JavaScript errors that might prevent your listener functions from being registered or executed properly.
Problem: Application slowing down over timeSolutions:
  • Remove unused listeners: Always remove event listeners when they’re no longer needed using removeEventListener with the same function reference used in addEventListener.
  • Clean up on page unload: Remove all event listeners before the user navigates away from the page to prevent memory leaks in single-page applications.
  • Handle route changes: In single-page applications, ensure you clean up event listeners when routes change, not just on full page reloads.
  • Use cleanup patterns: Create cleanup functions that remove all your event listeners and call them at appropriate lifecycle points in your application.
Problem: removeEventListener not workingSolutions:
  • Avoid inline functions: Don’t use anonymous or inline functions as event handlers if you need to remove them later. Inline functions create new function references each time, making them impossible to remove.
  • Store function references: Create named functions or store function references in variables before passing them to addEventListener. Use the same reference when calling removeEventListener.
  • Test removal: Verify that your event listeners are actually being removed by checking if they still fire after calling removeEventListener.

​
Next Steps

Custom Initial Messages

Create dynamic, personalized initial messages for users

Floating Initial Messages

Display floating messages over the chat bubble
⌘I