Events

Complete reference for all events emitted by the Alhena Website SDK, organized by category with callback signatures and examples.

The Alhena Website SDK emits JavaScript events that allow you to respond to user interactions and widget state changes. Use these events to customize the user experience, track analytics, or integrate with other systems.

Subscribing to Events

Use the window.gleenWidget.on() method to subscribe to events:

window.gleenWidget.on('event_name', function(data) {
    // Handle the event
    console.log('Event fired:', data);
});

Event subscriptions should be set up after the SDK script loads. For best results, place your event handlers after the SDK script tag or inside a widget:loaded handler.

---

Quick Reference

Event	Category	Description
widget:loaded	Widget	Widget finished loading
widget:opened	Widget	Widget was opened
widget:closed	Widget	Widget was closed
ticket:message_submitted	Ticket	User sent a message
ticket:bot_response_finished	Ticket	Bot completed its response
ticket:agent_handoff	Ticket	Ticket transferred to human agent
ticket:agent_handoff_initiated	Ticket	Human handoff process started
ticket:link_clicked	Ticket	User clicked a link in chat
ticket:input_focused	Ticket	User focused the input field
ticket:attachment_added	Ticket	User attached a file
product:added_to_cart	E-commerce	User clicked "Add to Cart"
products:added_to_cart	E-commerce	Multiple products added to cart
product:page_opened	E-commerce	User clicked a product link
product:displayed	E-commerce	Product card was rendered
faqs:question_clicked	FAQ	User clicked a FAQ question
faqs:message_submitted	FAQ	User submitted a FAQ question
faqs:bot_response_finished	FAQ	Bot finished FAQ response
experiment:loaded	Experiment	A/B test group assigned
icebreaker_question:postback	Widget	User clicked an icebreaker

---

Widget Events

Events related to the widget's state and lifecycle.

widget:loaded

Fired when the widget has finished loading and is ready for interaction. Use this event to safely set up other event handlers or perform initial configuration.

Callback: None

window.gleenWidget.on('widget:loaded', function() {
    console.log('Widget is ready');
    // Safe to call other widget methods now
    window.gleenWidget.showNudge({
        message: 'Need help? Ask me anything!'
    });
});

widget:opened

Fired when the chat widget is opened (expanded).

Callback: None

window.gleenWidget.on('widget:opened', function() {
    console.log('User opened the chat widget');
    // Track in analytics
    gtag('event', 'chat_opened');
});

widget:closed

Fired when the chat widget is closed (minimized).

Callback: None

window.gleenWidget.on('widget:closed', function() {
    console.log('User closed the chat widget');
});

---

Ticket/Conversation Events

Events related to chat conversations and messages.

ticket:message_submitted

Fired when the user sends a message in the chat widget.

Callback parameters:

Property	Type	Description
text	string	The message text sent by the user
submitAction	string	The action that triggered the submission

window.gleenWidget.on('ticket:message_submitted', function(data) {
    console.log('User sent:', data.text);
});

ticket:bot_response_finished

Fired when the AI bot has finished generating and streaming its response.

Callback parameters:

Property	Type	Description
response	string	The complete bot response text

window.gleenWidget.on('ticket:bot_response_finished', function(data) {
    console.log('Bot responded:', data.response);
});

ticket:agent_handoff

Fired when a ticket has been successfully created in the helpdesk system after the user submits their email during human handoff.

Callback parameters:

Property	Type	Description
ticketId	string	The ID of the created ticket
email	string	The user's email address

window.gleenWidget.on('ticket:agent_handoff', function(data) {
    console.log('Ticket created:', data.ticketId);
    console.log('User email:', data.email);

    // Optionally close the widget after handoff
    setTimeout(function() {
        window.gleenWidget.close();
    }, 5000);
});

ticket:agent_handoff_initiated

Fired when the AI determines that the conversation should be transferred to a human agent. At this stage, the AI is waiting for the user to submit their email address.

Callback: None

window.gleenWidget.on('ticket:agent_handoff_initiated', function() {
    console.log('Human handoff started - waiting for user email');

    // Example: Switch to another support widget
    // window.gleenWidget.closeTicket();
    // window.gleenWidget.close();
    // loadAlternativeSupportWidget();
});

ticket:link_clicked

Fired when the user clicks a link within a chat message.

Callback parameters:

Property	Type	Description
url	string	The URL that was clicked
text	string	The link text

window.gleenWidget.on('ticket:link_clicked', function(data) {
    console.log('User clicked link:', data.url);
    // Track outbound link clicks
});

ticket:input_focused

Fired when the user focuses on the message input field.

Callback: None

window.gleenWidget.on('ticket:input_focused', function() {
    console.log('User is about to type a message');
});

ticket:attachment_added

Fired when the user attaches a file to their message.

Callback parameters:

Property	Type	Description
fileName	string	Name of the attached file
fileType	string	MIME type of the file
fileSize	number	Size in bytes

window.gleenWidget.on('ticket:attachment_added', function(data) {
    console.log('User attached:', data.fileName);
});

---

E-commerce Events

Events for e-commerce integrations. These events help you connect the chat widget with your shopping cart and product pages.

Important: By adding an event handler for the product:added_to_cart event, you will cause the "Add to Cart" button to appear in product cards. You must implement custom JavaScript specific to your e-commerce platform to handle this event.

product:added_to_cart

Fired when a customer clicks the "Add to Cart" button on a product card within the chat widget.

Callback parameters:

Property	Type	Description
variantId	string	The product variant ID
productId	string	The product ID
quantity	number	Quantity to add (usually 1)
price	number	Product price

window.gleenWidget.on('product:added_to_cart', function(data) {
    console.log('Add to cart - Variant:', data.variantId);
    console.log('Quantity:', data.quantity);

    // Example: Add to Shopify cart via AJAX
    fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            id: data.variantId,
            quantity: data.quantity
        })
    }).then(function() {
        // Show cart drawer or redirect to cart
        openCartDrawer();
    });
});

products:added_to_cart

Fired when multiple products are added to cart at once (e.g., from a product bundle or quiz results).

Callback parameters:

Property	Type	Description
products	array	Array of product objects

Each product object contains:

Property	Type	Description
variantId	string	The product variant ID
productId	string	The product ID
quantity	number	Quantity to add

window.gleenWidget.on('products:added_to_cart', function(data) {
    console.log('Adding multiple products:', data.products.length);

    data.products.forEach(function(product) {
        // Add each product to your cart
        addToCart(product.variantId, product.quantity);
    });
});

product:page_opened

Fired when a customer clicks a product link rendered inside the chat widget.

Callback parameters:

Property	Type	Description
variantId	string	The product variant ID
productId	string	The product ID
url	string	The product page URL

window.gleenWidget.on('product:page_opened', function(data) {
    console.log('User opened product:', data.variantId);
    // Optionally track product views
});

product:displayed

Fired when a product card is rendered inside the chat widget.

Callback parameters:

Property	Type	Description
variantId	string	The product variant ID
productId	string	The product ID

window.gleenWidget.on('product:displayed', function(data) {
    console.log('Product displayed:', data.variantId);
    // Track product impressions
});

---

FAQ Events

Events for the Product FAQ feature.

faqs:question_clicked

Fired when a user clicks on an AI-generated FAQ question.

Callback parameters:

The callback receives the question text as a string directly.

window.gleenWidget.on('faqs:question_clicked', function(questionText) {
    console.log('FAQ question clicked:', questionText);
});

faqs:message_submitted

Fired when a user submits a custom question in the product FAQ text box.

Callback parameters:

The callback receives the user's question as a string directly.

window.gleenWidget.on('faqs:message_submitted', function(userMessage) {
    console.log('FAQ question asked:', userMessage);
});

faqs:bot_response_finished

Fired when the AI completes its response in the FAQ widget. This applies to both clicked FAQ questions and custom user questions.

Callback parameters:

The callback receives the AI's complete response as a string directly.

window.gleenWidget.on('faqs:bot_response_finished', function(responseText) {
    console.log('FAQ response:', responseText);
});

---

Experiment Events

Events for A/B testing functionality.

experiment:loaded

Fired when an active A/B test experiment is running and the user has been assigned to a group. See A/B Testing for full documentation.

Callback parameters:

The callback receives a string directly (not an object): either 'test' or 'control'.

window.gleenWidget.on('experiment:loaded', function(experimentGroup) {
    console.log('User assigned to:', experimentGroup);
    // experimentGroup is 'test' or 'control'

    if (experimentGroup === 'control') {
        // Load alternative support solution for control group
        loadZendeskWidget();
    }
});

---

Icebreaker Events

Events related to conversation starters and quick replies.

icebreaker_question:postback

Fired when a user clicks an icebreaker question or quick reply button.

Callback parameters:

Property	Type	Description
question_text	string	The icebreaker question text
type	string	The type of icebreaker
postback_payload	string	The postback payload value

window.gleenWidget.on('icebreaker_question:postback', function(data) {
    console.log('Icebreaker clicked:', data.question_text);
});

---

Complete Example

Here's a complete example showing how to set up multiple event handlers:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Alhena Events Example</title>
</head>
<body>

<!-- Alhena SDK -->
<script>
document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai'
};
</script>
<script src="https://app.alhena.ai/sdk/gleenWidget.js"></script>

<script>
// Widget lifecycle events
window.gleenWidget.on('widget:loaded', function() {
    console.log('Chat widget ready');
});

window.gleenWidget.on('widget:opened', function() {
    gtag('event', 'chat_widget_opened');
});

window.gleenWidget.on('widget:closed', function() {
    gtag('event', 'chat_widget_closed');
});

// Conversation events
window.gleenWidget.on('ticket:message_submitted', function(data) {
    gtag('event', 'chat_message_sent', {
        message_length: data.text.length
    });
});

window.gleenWidget.on('ticket:agent_handoff', function(data) {
    gtag('event', 'human_handoff_completed', {
        ticket_id: data.ticketId
    });
});

// E-commerce events
window.gleenWidget.on('product:added_to_cart', function(data) {
    // Add to your cart
    addToCart(data.variantId, data.quantity);

    // Track in analytics
    gtag('event', 'add_to_cart', {
        currency: 'USD',
        items: [{
            item_id: data.productId,
            item_variant: data.variantId,
            quantity: data.quantity
        }]
    });
});

// A/B testing
window.gleenWidget.on('experiment:loaded', function(experimentGroup) {
    gtag('event', 'experiment_assigned', {
        experiment_group: experimentGroup
    });
});
</script>

</body>
</html>

---

Related Resources

• JavaScript API - Complete method reference

• A/B Testing - Experiment setup and events

• Cart & Checkout Events - Revenue tracking

• Examples - Code examples for common use cases