alby-chatbot

This documentation provides information about the events that the alby-chatbot widget publishes to the browser during its lifecycle.

Core Events

All core events follow the alby:Chatbot:: namespace pattern:

• alby:Chatbot::LauncherButtonRendered
• alby:Chatbot::LauncherButtonClicked
• alby:Chatbot::Opened
• alby:Chatbot::Closed
• alby:Chatbot::Submitted
• alby:Chatbot::ThreadCreated
• alby:Chatbot::ResponseFinished
• alby:Chatbot::FollowUpClicked
• alby:Chatbot::UserFeedback
• alby:Chatbot::UserThumbsUp
• alby:Chatbot::UserThumbsDown
• alby:Chatbot::Click:Link

Event Details

alby:Chatbot::LauncherButtonRendered

• Description: This event is dispatched when the launcher button is fully loaded and rendered on the screen.
• Usage: You can listen for this event to trigger any post-render actions, such as adjusting layout, displaying additional elements, or logging analytics data.
• Payload / Example:
  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
  }
  */
  document.addEventListener('alby:Chatbot::LauncherButtonRendered', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Launcher Button Rendered', { widgetId });
  });

alby:Chatbot::LauncherButtonClicked

• Description: Fired when a user clicks on the launcher button to open or close the chat window.

• Usage: Track launcher button engagement, trigger UI updates, or perform analytics tracking.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    isOpen: boolean;     // Whether the chat is now open (true) or closed (false)
  }
  */
  document.addEventListener('alby:Chatbot::LauncherButtonClicked', function(e) { 
    const { widgetId, isOpen } = e.detail;
    
    analytics.track('Launcher Button Clicked', { widgetId, isOpen });
  });

alby:Chatbot::Opened

• Description: Dispatched when the chat window is opened and becomes visible to the user.

• Usage: Listen for this event to track chat window visibility, trigger analytics, or perform actions that should occur when the chat opens.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
  }
  */
  document.addEventListener('alby:Chatbot::Opened', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Chat Opened', { widgetId });
  });

alby:Chatbot::Closed

• Description: Dispatched when the chat window is closed and hidden from the user.

• Usage: Track chat session duration, trigger cleanup actions, or perform analytics when the chat closes.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
  }
  */
  document.addEventListener('alby:Chatbot::Closed', function(e) { 
    const { widgetId } = e.detail;
    
    analytics.track('Chat Closed', { widgetId });
  });

alby:Chatbot::Submitted

• Description: Fired when a user submits a message to the chatbot.

• Usage: Track user interactions, monitor message content, or trigger custom actions when messages are submitted.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    input: string;       // The user's submitted message
    threadId: string;    // Unique identifier for the conversation thread
    response: string;    // The AI's response to the message
  }
  */
  document.addEventListener('alby:Chatbot::Submitted', function(e) { 
    const { widgetId, input, threadId, response } = e.detail;
    
    analytics.track('Message Submitted', { widgetId, input, threadId, response });
  });

alby:Chatbot::ThreadCreated

• Description: Dispatched when a new conversation thread is created.

• Usage: Track new conversation starts, initialize session data, or perform analytics for new threads.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    threadId: string;    // Unique identifier for the new conversation thread
    type: "freeform" | "button" | "followUp";  // Type of interaction that created the thread
    input: string;       // The initial user input
  }
  */
  document.addEventListener('alby:Chatbot::ThreadCreated', function(e) { 
    const { widgetId, threadId, type, input, response } = e.detail;
    
    analytics.track('Thread Created', { widgetId, threadId, type, input });
  });

alby:Chatbot::ResponseFinished

• Description: Fired when the AI has completed generating a response to a user message.

• Usage: Track response completion, trigger UI updates, or perform actions after AI responses are finished.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    threadId: string;    // Unique identifier for the conversation thread
    messageId: string;   // Unique identifier for the specific message
    type: "freeform" | "button" | "followUp";  // Type of interaction
    input: string;       // The user's input that triggered the response
    response: string;    // The completed AI response
  }
  */
  document.addEventListener('alby:Chatbot::ResponseFinished', function(e) { 
    const { widgetId, threadId, messageId, type, input, response } = e.detail;
    
    analytics.track('Response Finished', { widgetId, threadId, messageId, type, input, response });
  });

alby:Chatbot::FollowUpClicked

• Description: Fired when a user clicks on a follow-up suggestion button.

• Usage: Track follow-up engagement, monitor user interaction patterns, or trigger custom actions for follow-up clicks.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    threadId: string;    // Unique identifier for the conversation thread
    input: string;       // The follow-up question text
    response: string;    // The AI's response to the follow-up
  }
  */
  document.addEventListener('alby:Chatbot::FollowUpClicked', function(e) { 
    const { widgetId, threadId, input, response } = e.detail;
    
    analytics.track('Follow-up Clicked', { widgetId, threadId, input, response });
  });

alby:Chatbot::UserFeedback

• Description: Dispatched when a user provides feedback (thumbs up/down) on an AI response.

• Usage: Track user satisfaction, monitor response quality, or trigger quality improvement workflows.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    isPositive: boolean; // Whether the feedback was positive (true) or negative (false)
    threadId: string;    // Unique identifier for the conversation thread
    messageId: string;   // Unique identifier for the specific message
    response: string;    // The AI response that received feedback
  }
  */
  document.addEventListener('alby:Chatbot::UserFeedback', function(e) { 
    const { widgetId, isPositive, threadId, messageId, response } = e.detail;
    
    analytics.track('User Feedback', { widgetId, isPositive, threadId, messageId, response });
  });

alby:Chatbot::UserThumbsUp

• Description: Dispatched when a user provides feedback (thumbs up/down) on an AI response.

• Usage: Track positive feedback, monitor user satisfaction, and measure chatbot response quality.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    threadId: string;    // Unique identifier for the conversation thread
    message: string;   // The specific message the user rated
  }
  */
  document.addEventListener('alby:Chatbot::UserThumbsUp', function(e) { 
    const { widgetId, threadId, message } = e.detail;
    
    analytics.track('User Thumbs Up', { widgetId, threadId, message });
  });

alby:Chatbot::UserThumbsDown

• Description: Dispatched when a user provides feedback (thumbs up/down) on an AI response.

• Usage: Track negative feedback, identify poor responses, and feed insights into quality improvement pipelines.

• Payload / Example:

  TypeScript

  /*
  {
    widgetId: string;    // Unique identifier for the widget instance
    threadId: string;    // Unique identifier for the conversation thread
    message: string;   // The specific message the user rated
  }
  */
  document.addEventListener('alby:Chatbot::UserThumbsDown', function(e) { 
    const { widgetId, threadId, message } = e.detail;
    
    analytics.track('User Thumbs Down', { widgetId, threadId, message });
  });

alby:Chatbot::Click:Link

• Description: Fired when a shopper clicks on a link generated by the AI.

• Usage: Listen for this event to track link interactions, validate outbound links, or analyze which types of resources users find most helpful in AI responses.

• Payload / Example:

  TypeScript

  /*
  {
    url: string;        // The URL that was clicked
    widgetId: string;  // Unique identifier for the widget instance
  }
  */
  
  document.addEventListener('alby:Chatbot::Click:Link', (e) => {
    const { url, widgetId } = e.detail;
    analytics.track('Response Link Clicked', {
      url,
      widgetId,
      domain: new URL(url).hostname
    });
  });