alby-chatbot

Help your shoppers discover, research, and buy with confidence, wherever they are on your website.

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

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:
    /*
    {
      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:

    /*
    {
      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:

    /*
    {
      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:

    /*
    {
      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:

    /*
    {
      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:

    /*
    {
      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
      response: string;    // The AI's initial response
    }
    */
    document.addEventListener('alby:Chatbot::ThreadCreated', function(e) { 
      const { widgetId, threadId, type, input, response } = e.detail;
      
      analytics.track('Thread Created', { widgetId, threadId, type, input, response });
    });
    

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:

    /*
    {
      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:

    /*
    {
      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:

    /*
    {
      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 });
    });