Custom Events

Fast Simon Shopper Assistant dispatches custom events for integration with analytics, external controls, and other use cases. This way you are able to target important events the moment they are fired.

Getting Started

Shopper Assistant custom events

Register an event listener using a script tag located in the <head>
Each time an event is fired within the Shopper Assistant, we will dispatch the custom event including all the relevant data.

Register a new custom event listener & run a callback once fired

<script>
    function chatReadyCallback() {
        console.log('Shopper Assistant is ready!');
    }

    window.addEventListener('fs-chat-ready', (e) => {
        chatReadyCallback();
    });
</script>

Dispatched Events (Listen to these)

These events are dispatched BY the Shopper Assistant and you can listen to them:

Chat State Events

Event Name	Description	Event Data
"fs-chat-ready"	Event is fired when chat is initialized	None
"fs-chat-open-state-changed"	Event is fired when chat opens or closes	boolean (true = open, false = closed)
"fast-chat-assistant-ready"	Event is fired when hooks system is ready	None

Product Interaction Events

These events match the PLP (Product Listing Page) event naming convention:

Event Name	Description	Event Data
"fs-custom-events-product-clicked"	Event is fired when clicking on a product	{productId: string, productURL: string}
"fs-custom-events-quick-view-btn-clicked"	Event is fired when clicking quick view button	{productId: string, productURL: string}
"fs-custom-events-product-quick-add-clicked"	Event is fired when clicking quick add button	{productId: string, productURL: string}
"fs-custom-events-product-added-to-cart"	Event is fired when product added to cart	{productId: string, variantId: string, productURL: string}

Example: Listen to chat open/close events

<script>
    window.addEventListener('fs-chat-open-state-changed', (e) => {
        const isOpen = e.detail;
        console.log('Chat is now:', isOpen ? 'open' : 'closed');

        // Your analytics or custom logic here
        if (isOpen) {
            // Track chat open event
            analytics.track('Chat Opened');
        }
    });
</script>

Example: Initialize hooks when chat is ready

<script>
    window.addEventListener('fast-chat-assistant-ready', () => {
        // Register your hooks here
        window.FastSimonChat.registerHook(
            window.FastSimonChat.CustomizationEvent.ChatHeader,
            ({element, title}) => {
                console.log('Chat header updated:', title);
            }
        );
    });
</script>

If you want to use your own quick view implementation instead of Fast Simon's default modal:

<script>
    // 1. Initialize chat with defaultStoreQuickview enabled
    window.__fastChatConfig = {
        store_uuid: 'your-store-uuid',
        defaultStoreQuickview: true  // Disable Fast Simon's quick view modal
    };

    // 2. Listen to the quick view event and open your modal
    window.addEventListener('fs-custom-events-quick-view-btn-clicked', (e) => {
        const {productId, productURL} = e.detail;

        // Open YOUR custom quick view modal
        openMyCustomQuickView(productId, productURL);
    });

    function openMyCustomQuickView(productId, productURL) {
        // Your custom quick view implementation
        console.log(`Opening custom quick view for product: ${productId}`);

        // Example: Open a custom modal
        const modal = document.getElementById('my-quick-view-modal');
        modal.style.display = 'block';

        // Load product data and display it
        fetch(`/products/${productId}.json`)
            .then(res => res.json())
            .then(product => {
                // Populate your modal with product data
                document.getElementById('modal-product-title').textContent = product.title;
                document.getElementById('modal-product-price').textContent = product.price;
                // ... more custom logic
            });
    }
</script>

Example: Using your own custom quick add flow

If you want to handle quick add clicks with your own logic (common for stores with custom quick view):

<script>
    // 1. Initialize chat with BOTH options to fully control product interactions
    window.__fastChatConfig = {
        store_uuid: 'your-store-uuid',
        defaultStoreQuickview: true,  // Disable Fast Simon's quick view
        defaultStoreQuickAdd: true    // Disable Fast Simon's quick add logic
    };

    // 2. Handle quick add clicks by opening YOUR quick view
    window.addEventListener('fs-custom-events-product-quick-add-clicked', (e) => {
        const {productId, productURL} = e.detail;

        // Instead of Fast Simon's add-to-cart logic, open YOUR quick view
        openMyCustomQuickView(productId);
    });

    // 3. Also handle quick view button clicks the same way
    window.addEventListener('fs-custom-events-quick-view-btn-clicked', (e) => {
        const {productId, productURL} = e.detail;
        openMyCustomQuickView(productId);
    });

    function openMyCustomQuickView(productId) {
        // Your unified quick view logic for both quick view and quick add
        console.log(`Opening quick view for product: ${productId}`);

        // Example: Use your theme's native quick view
        if (window.Shopify && window.Shopify.showQuickView) {
            window.Shopify.showQuickView(productId);
        }

        // Or use a custom implementation
        else {
            MyStore.QuickView.open(productId);
        }
    }
</script>

Example: Matching your PLP behavior exactly

Many customers configure PLP to open their custom quick view on quick add click. Match that behavior:

<script>
    // Same configuration for BOTH PLP and Chat Assistant
    window.__fastChatConfig = {
        store_uuid: 'your-store-uuid',
        defaultStoreQuickAdd: true  // Match PLP setting
    };

    // Unified handler works for both PLP and Chat Assistant
    window.addEventListener('fs-custom-events-product-quick-add-clicked', (e) => {
        const {productId, productURL} = e.detail;

        // Use the SAME quick view function you use for PLP
        openStoreQuickView(productId);
    });

    // Your existing function (already used by PLP)
    function openStoreQuickView(productId) {
        // This works for clicks from PLP AND Chat Assistant
        document.getElementById('quick-view-modal').classList.add('active');
        loadProductData(productId);
    }
</script>

Received Events (Dispatch these to control the chat)

These events can be dispatched TO the Shopper Assistant to control its behavior:

Event Name	Description	Event Data
"fsChatbotCustomEvent"	Main event hub for controlling chat behavior	{eventName: string, data: any}

Available Sub-Events via fsChatbotCustomEvent

Sub-Event Name	Description	Data Structure
"fs-open-chat"	Opens the chat window	{messages?: {messages: Message[]}} (optional)
"fs-close-chat"	Closes the chat window	None
"fs-toggle-chat"	Toggles chat open/close state	None
"ac-question-clicked"	Send a predefined question to chat	string (the question text)
"fs-page-context-changed"	Update the current page context	object (page context data)

Example: Open the chat programmatically

<script>
    function openChat() {
        document.dispatchEvent(new CustomEvent('fsChatbotCustomEvent', {
            detail: {
                eventName: 'fs-open-chat',
                data: {}
            }
        }));
    }

    // Call when needed
    openChat();
</script>

Example: Open chat with pre-loaded conversation

<script>
    function openChatWithHistory() {
        const previousMessages = [
            {
                role: 'user',
                content: 'Show me running shoes',
                type: 'regular'
            },
            {
                role: 'assistant',
                content: 'Here are some great running shoes',
                type: 'regular',
                products: [/* product data */]
            }
        ];

        document.dispatchEvent(new CustomEvent('fsChatbotCustomEvent', {
            detail: {
                eventName: 'fs-open-chat',
                data: {
                    messages: {
                        messages: previousMessages
                    }
                }
            }
        }));
    }
</script>

Example: Send a question to the chat

<script>
    function askChatQuestion(question) {
        document.dispatchEvent(new CustomEvent('fsChatbotCustomEvent', {
            detail: {
                eventName: 'ac-question-clicked',
                data: question
            }
        }));
    }

    // Example usage
    askChatQuestion('What are your best-selling products?');
</script>

Example: Toggle chat from custom button

<button onclick="toggleChat()">Chat with us</button>

<script>
    function toggleChat() {
        document.dispatchEvent(new CustomEvent('fsChatbotCustomEvent', {
            detail: {
                eventName: 'fs-toggle-chat',
                data: {}
            }
        }));
    }
</script>

Example: Update page context to make the assistant better understand the page the user sees

<script>
    function updatePageContext() {
        const pageContext = {
            pageType: 'product',
            productId: '12345',
            category: 'electronics',
            price: 299.99
        };

        document.dispatchEvent(new CustomEvent('fsChatbotCustomEvent', {
            detail: {
                eventName: 'fs-page-context-changed',
                data: pageContext
            }
        }));

        // Store for persistence
        localStorage.setItem('fs-chat-page-context-data', JSON.stringify(pageContext));
    }

    // Call when page context changes (e.g., viewing a new product)
    updatePageContext();
</script>

Configuration Options

defaultStoreQuickview

Use this option to disable Fast Simon's quick view modal and handle it yourself:

window.__fastChatConfig = {
    store_uuid: 'your-store-uuid',
    defaultStoreQuickview: true  // Event fires, but modal doesn't open
};

When enabled:

fs-custom-events-quick-view-btn-clicked event is still dispatched
Fast Simon's quick view modal does NOT open
You can listen to the event and open your own custom quick view

defaultStoreQuickAdd

Use this option to disable Fast Simon's quick add logic and handle it yourself:

window.__fastChatConfig = {
    store_uuid: 'your-store-uuid',
    defaultStoreQuickAdd: true  // Event fires, but no internal add-to-cart logic
};

When enabled:

fs-custom-events-product-quick-add-clicked event is still dispatched
Fast Simon's quick add logic does NOT execute (no direct add, no variant selector, no modal)
You can listen to the event and implement your own add-to-cart flow

Quick Add has 3 internal modes that are disabled when this option is true:

Direct add - Single variant products add directly to cart
Inline selector - Multiple variants with same attribute (e.g., only size) show inline selector
Variant modal - Multiple variants with different attributes (e.g., size + color) open modal

With defaultStoreQuickAdd: true, all 3 modes are skipped and you handle the click yourself.

Best Practices

Always check if the chat is ready before dispatching events to it
Store page context in localStorage when it changes to persist across page reloads
Test in both desktop and mobile to ensure events work correctly
Implement event listeners early in your page load to avoid missing events
Consider event order - Quick Add Click fires before Product Added to Cart
Use defaultStoreQuickview if you have a custom quick view implementation
Use defaultStoreQuickAdd if you want to handle quick add clicks yourself (common pattern: open custom quick view on quick add click)
Match PLP configuration - If your PLP uses custom quick view/add, use the same config for Chat Assistant for consistent UX

Custom Events

Getting Started​

Shopper Assistant custom events​

Register a new custom event listener & run a callback once fired​

Dispatched Events (Listen to these)​

Chat State Events​

Product Interaction Events​

Example: Listen to chat open/close events​

Example: Initialize hooks when chat is ready​

Example: Using your own custom quick view modal​

Example: Using your own custom quick add flow​

Example: Matching your PLP behavior exactly​

Received Events (Dispatch these to control the chat)​

Available Sub-Events via fsChatbotCustomEvent​

Example: Open the chat programmatically​

Example: Open chat with pre-loaded conversation​

Example: Send a question to the chat​

Example: Toggle chat from custom button​

Example: Update page context to make the assistant better understand the page the user sees​

Configuration Options​

defaultStoreQuickview​

defaultStoreQuickAdd​

Best Practices​