Skip to main content

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​

  1. Register an event listener using a script tag located in the <head>
  2. 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:

Event NameDescriptionEvent Data
"fs-chat-ready"Event is fired when chat is initializedNone
"fs-chat-open-state-changed"Event is fired when chat opens or closesboolean (true = open, false = closed)
"fast-chat-assistant-ready"Event is fired when hooks system is readyNone

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>

Received Events (Dispatch these to control the chat)​

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

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

Available Sub-Events via fsChatbotCustomEvent​

Sub-Event NameDescriptionData Structure
"fs-open-chat"Opens the chat window{messages?: {messages: Message[]}} (optional)
"fs-close-chat"Closes the chat windowNone
"fs-toggle-chat"Toggles chat open/close stateNone
"ac-question-clicked"Send a predefined question to chatstring (the question text)
"fs-page-context-changed"Update the current page contextobject (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>

Best Practices​

  1. Always check if the chat is ready before dispatching events to it
  2. Store page context in localStorage when it changes to persist across page reloads
  3. Test in both desktop and mobile to ensure events work correctly