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.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 activeaway: Agent is temporarily unavailableoffline: 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.