Event Listeners

Event Listeners Overview

Chatislav widgets emit events throughout their lifecycle, allowing you to respond to user interactions, widget state changes, and AI agent activities. This enables integrated experiences, analytics tracking, and custom behaviors.

 

Available Events

Event Name	Description	When Triggered
ready	Widget initialization complete	When widget finishes loading
open	Widget opened	When chat window becomes visible
close	Widget closed	When chat window is hidden
message	New message in conversation	When user or AI sends a message
user-session-set	User session updated	When user identification is set
action-call	Client-side action triggered	When AI agent executes a registered action
action-result	Client-side action completed	When action returns a result
prompter-message	User message sent	When user sends a message
assistant-message	AI response received	When AI agent responds

 

Adding Event Listeners

Use the add_event_listener method to register callback functions:

window.chatislav.add_event_listener('open', function(event) {
  console.log('Chat widget opened!', event);
});

For specific widget instance:

window.chatislav.add_event_listener('open', function(event) {
  console.log('Chat widget opened!', event);
}, 'ctslv_bbl');

Event with Data Processing:

window.chatislav.add_event_listener('message', function(event) {
  console.log('New message:', event.data);
  console.log('Timestamp:', event.timestamp);
  console.log('Instance ID:', event.instanceId);
  
  // Custom logic
  trackMessageAnalytics(event.data);
}, 'ctslv_bbl');

 

Removing Event Listeners

function myEventHandler(event) {
  console.log('Event triggered:', event);
}

// Add listener
window.chatislav.add_event_listener('close', myEventHandler, 'ctslv_bbl');

// Remove listener
window.chatislav.remove_event_listener('close', myEventHandler, 'ctslv_bbl');

 

Instance ID Parameter

The optional instance_id parameter allows you to target specific widget instances when you have multiple widgets on the same page. The instance ID corresponds to the instance name used when initializing the widget script.

All Widgets (no instance_id):

window.chatislav.add_event_listener('ready', function(event) {
  console.log('Widget ready - applies to all widgets');
});

Specific Widget Instance:

window.chatislav.add_event_listener('ready', function(event) {
  console.log('ctslv_bbl widget ready');
}, 'ctslv_bbl');

 

Event Object Structure

Every event callback receives an object with:

{
  type: "event_name",        // Event type (e.g., "open", "message")
  data: { /* event data */ },  // Event-specific information
  timestamp: Date,           // When the event occurred
  instanceId: "string"       // Widget instance identifier
}

 

Widget Lifecycle Events

Ready Event:

window.chatislav.add_event_listener('ready', function(event) {
  console.log('Widget ready:', event.data.elementId);
  console.log('Instance ID:', event.instanceId);
  enableCustomUI();
}, 'ctslv_bbl');

Open/Close Events:

window.chatislav.add_event_listener('open', function(event) {
  console.log('Chat opened for instance:', event.instanceId);
  gtag('event', 'chat_opened');
  hideOtherHelpElements();
}, 'ctslv_bbl');

window.chatislav.add_event_listener('close', function(event) {
  console.log('Chat closed for instance:', event.instanceId);
  gtag('event', 'chat_closed');
  showOtherHelpElements();
}, 'ctslv_bbl');

 

Message Events

User Message Event:

window.chatislav.add_event_listener('prompter-message', function(event) {
  console.log('User sent:', event.data.content);
  console.log('From instance:', event.instanceId);
  
  // Trigger custom responses based on keywords
  if (event.data.content.toLowerCase().includes('pricing')) {
    highlightPricingSection();
  }
}, 'ctslv_bbl');

AI Assistant Message Event:

window.chatislav.add_event_listener('assistant-message', function(event) {
  console.log('AI responded:', event.data.content);
  console.log('From instance:', event.instanceId);
  
  if (event.data.content.includes('product recommendation')) {
    showProductCarousel();
  }
}, 'ctslv_bbl');

 

User Session Events

Monitor user identification changes. For detailed user session configuration, see User Session Identity.

window.chatislav.add_event_listener('user-session-set', function(event) {
  console.log('User session updated:', event.data.userSession);
  console.log('Instance ID:', event.instanceId);
  
  if (event.data.userSession.user_metadata) {
    updateUIForUser(event.data.userSession.user_metadata);
  }
}, 'ctslv_bbl');

 

Client-Side Action Events

Action Call Event:

window.chatislav.add_event_listener('action-call', function(event) {
  console.log('Action triggered:', event.data.action);
  console.log('From instance:', event.instanceId);
  
  if (event.data.action === 'process_payment') {
    showPaymentLoading();
  }
}, 'ctslv_bbl');

Action Result Event:

window.chatislav.add_event_listener('action-result', function(event) {
  console.log('Action completed:', event.data.action, event.data.status);
  console.log('From instance:', event.instanceId);
  
  hideLoadingIndicators();
  
  if (event.data.status === 'success') {
    showSuccessMessage(event.data.result.message);
  } else {
    showErrorMessage(event.data.result.message);
  }
}, 'ctslv_bbl');

 

Multiple Widget Instances

When working with multiple widget instances on the same page, use the instance ID to target specific widgets:

// Primary support widget
window.chatislav.add_event_listener('open', function(event) {
  console.log('Primary support chat opened');
  gtag('event', 'support_chat_opened');
}, 'ctslv_support');

// Sales widget  
window.chatislav.add_event_listener('open', function(event) {
  console.log('Sales chat opened');
  gtag('event', 'sales_chat_opened');
}, 'ctslv_sales');

 

Comprehensive Integration Example

function setupChatIntegration() {
  let sessionStartTime;
  let messageCount = 0;
  
  // Track session start
  window.chatislav.add_event_listener('open', function(event) {
    sessionStartTime = new Date();
    messageCount = 0;
    document.getElementById('help-button').style.display = 'none';
    gtag('event', 'chat_session_started', {
      instance_id: event.instanceId
    });
  }, 'ctslv_bbl');
  
  // Track session end
  window.chatislav.add_event_listener('close', function(event) {
    if (sessionStartTime) {
      const duration = new Date() - sessionStartTime;
      gtag('event', 'chat_session_ended', {
        duration_seconds: Math.round(duration / 1000),
        message_count: messageCount,
        instance_id: event.instanceId
      });
    }
    document.getElementById('help-button').style.display = 'block';
  }, 'ctslv_bbl');
  
  // Count messages
  window.chatislav.add_event_listener('message', function(event) {
    messageCount++;
    console.log('Message count:', messageCount, 'Instance:', event.instanceId);
  }, 'ctslv_bbl');
  
  // Handle action feedback
  window.chatislav.add_event_listener('action-call', function(event) {
    if (event.data.action === 'add_to_cart') {
      showLoadingSpinner('Adding to cart...');
    }
  }, 'ctslv_bbl');
  
  window.chatislav.add_event_listener('action-result', function(event) {
    hideLoadingSpinner();
    if (event.data.action === 'add_to_cart' && event.data.status === 'success') {
      updateCartIcon();
      showNotification('Item added!');
    }
  }, 'ctslv_bbl');
}

setupChatIntegration();

 

Voice Widget Events

Coming soon.

Error Handling

Always implement error handling in event listeners:

window.chatislav.add_event_listener('action-result', function(event) {
  try {
    if (event.data.status === 'error') {
      console.error('Action failed:', event.data.result, 'Instance:', event.instanceId);
      showUserFriendlyError('Something went wrong.');
    } else {
      processSuccessfulAction(event.data);
    }
  } catch (error) {
    console.error('Error processing action result:', error, 'Instance:', event.instanceId);
  }
}, 'ctslv_bbl');

 

Best Practices

1. Remove Unused Listeners - Clean up listeners to prevent memory leaks
2. Keep Handlers Lightweight - Move heavy processing to async functions
3. Handle Missing Data - Check if expected data exists before using it
4. Use Descriptive Names - Name handler functions clearly for debugging
5. Test Event Flows - Verify listeners work across different interaction patterns
6. Use Instance IDs - Always specify instance_id when working with multiple widgets