Docs

Widget Events

Listen to widget events and execute code at the right time.

Heyo provides event callbacks to help you execute code at specific moments in the widget lifecycle.

onReady Callback

Use onReady() to execute code when the widget is fully loaded and initialized:

HEYO.onReady(() => {
    console.log('Widget is ready!');
});

If the widget is already ready when you call onReady(), the callback is executed immediately. Otherwise, it's queued and called once initialization completes.

onOpen Callback

Use onOpen() to execute code when the chat widget is opened:

HEYO.onOpen(() => {
    console.log('Chat was opened');
});

The callback is triggered every time the chat is opened, whether by the user clicking the widget, or programmatically via HEYO.open() or HEYO.toggle().

Examples with onOpen

Track when users engage with chat:

HEYO.onOpen(() => {
    analytics.track('chat_opened');
});

Update UI when chat opens:

HEYO.onOpen(() => {
    document.body.classList.add('chat-open');
});

Pause background activities:

HEYO.onOpen(() => {
    pauseAutoplayVideos();
});

HEYO.onClose(() => {
    resumeAutoplayVideos();
});

onClose Callback

Use onClose() to execute code when the chat widget is closed:

HEYO.onClose(() => {
    console.log('Chat was closed');
});

The callback is triggered every time the chat is closed, whether by the user clicking the close button, pressing Escape, or programmatically via HEYO.close().

Examples with onClose

Track when users close the chat:

HEYO.onClose(() => {
    analytics.track('chat_closed');
});

Update UI when chat closes:

HEYO.onClose(() => {
    document.body.classList.remove('chat-open');
});

Multiple callbacks for different purposes:

// Track analytics
HEYO.onClose(() => {
    analytics.track('chat_closed');
});

// Update UI
HEYO.onClose(() => {
    showFeedbackPrompt();
});

onAgentStatusChange Callback

Use onAgentStatusChange() to execute code when the agent's status changes:

HEYO.onAgentStatusChange((status) => {
    console.log('Agent status changed to:', status);
    
    // Update your UI based on status
    if (status === 'online') {
        showNotification('Support is now available!');
    }
});

The callback is called immediately with the current status when you register it, then again whenever the status changes.

Agent Status Values

The callback receives one of three status values:

online: Agent is available and active
away: Agent is temporarily unavailable
offline: Agent is not available

See Agent Status for more details on agent availability and the "Hide when offline" feature.

Examples with onAgentStatusChange

Update UI based on availability:

const statusIndicator = document.getElementById('support-status');

HEYO.onAgentStatusChange((status) => {
    if (status === 'online') {
        statusIndicator.textContent = '🟢 Chat available';
        statusIndicator.style.color = '#22c55e';
    } else if (status === 'away') {
        statusIndicator.textContent = '🟡 Be right back';
        statusIndicator.style.color = '#f59e0b';
    } else {
        statusIndicator.textContent = '⚫ Leave a message';
        statusIndicator.style.color = '#6b7280';
    }
});

Auto-open chat when agent comes online:

let hasPrompted = false;

HEYO.onAgentStatusChange((status) => {
    if (status === 'online' && !hasPrompted) {
        hasPrompted = true;
        setTimeout(() => HEYO.open(), 3000);
    }
});

Multiple callbacks for different purposes:

// Update UI
HEYO.onAgentStatusChange((status) => {
    updateSupportButton(status);
});

// Track analytics
HEYO.onAgentStatusChange((status) => {
    analytics.track('agent_status_changed', { status });
});

onReady - When to use

When to use onReady

You typically don't need onReady() because the SDK automatically queues all method calls until the widget is ready. However, it's useful when you need to:

Check if the widget has loaded successfully
Execute logic that depends on the widget being initialized
Integrate with third-party analytics or monitoring tools

When NOT to use onReady

You don't need onReady() for regular widget methods:

// ❌ Not needed - these work fine without onReady
HEYO.onReady(() => {
    HEYO.identify({ userId: '123' });
    HEYO.open();
    HEYO.configure({ widgetColor: '#10b981' });
});

// ✅ Just call them directly - they're automatically queued
HEYO.identify({ userId: '123' });
HEYO.open();
HEYO.configure({ widgetColor: '#10b981' });

Real-World Examples

Confirm widget loaded successfully:

HEYO.onReady(() => {
    console.log('Heyo widget loaded successfully');
    analytics.track('chat_widget_loaded');
});

Initialize based on async data:

// Fetch user data asynchronously
async function initializeChat() {
    const user = await fetchCurrentUser();
    
    // Wait for widget to be ready before identifying
    HEYO.onReady(() => {
        if (user) {
            HEYO.identify({
                userId: user.id,
                email: user.email,
                name: user.name,
            });
        }
    });
}

initializeChat();

Integration with monitoring tools:

HEYO.onReady(() => {
    // Report to your monitoring service
    Sentry.addBreadcrumb({
        category: 'chat',
        message: 'Chat widget initialized',
        level: 'info',
    });
});

Pro tip: For most use cases, you don't need onReady(). The SDK handles queueing automatically, so you can call methods like identify(), open(), and configure() immediately after loading the script.

Agent Status

Monitor agent availability and respond to status changes in real-time.

Tags and Custom Fields

Add metadata to visitors with tags and custom fields for better categorization and context.