Agent Status

Heyo provides methods to check agent status and listen for status changes, helping you create more dynamic experiences based on agent availability.

Agent Statuses

Agents can have three statuses:

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

Automatic vs Manual Status

On the agent side (in the dashboard), agents can operate in two modes:

• Auto mode: The agent's status automatically transitions between online and away based on activity (e.g., going away after 5 minutes of inactivity)
• Manual mode: The agent manually sets their status to online, away, or offline, overriding automatic behavior

From the visitor's perspective (your website), you only see the current status value (online, away, or offline) regardless of which mode the agent is using

Getting Current Status

Use getAgentStatus() to check the current agent status:

const status = HEYO.getAgentStatus();

switch (status) {
    case 'online':
        console.log('Agent is available to chat');
        break;
    case 'away':
        console.log('Agent is away but may return soon');
        break;
    case 'offline':
        console.log('Agent is offline');
        break;
}

Listening to Status Changes

You can react to agent status changes using the onAgentStatusChange() callback:

HEYO.onAgentStatusChange((status) => {
    console.log('Agent is now:', status);
});

Hide Widget When Offline

You can enable the "Hide when offline" option in your Project Settings to automatically hide the widget when all agents are offline.

How it works

When enabled:

• The widget is automatically hidden when all agents go offline
• The widget only reappears when agents come online if the user had shown interest (e.g., by calling HEYO.open() or HEYO.show())
• This prevents the widget from suddenly appearing on pages where it was never displayed

Examples:

• Page loads with all agents offline → widget stays hidden
• Page loads with agents online → widget shows normally
• Widget was visible, agents go offline → widget hides
• Widget was visible before going offline, agents come back online → widget re-appears
• Widget was never shown, agents come online → widget stays hidden (respects user preference)

Force showing/opening when offline

You can override the "hide when offline" behavior:

// Show the widget even if hideWhenOffline is enabled and all agents are offline
HEYO.show({ force: true });

// Open the chat even if hideWhenOffline is enabled and all agents are offline
HEYO.open({ force: true });

This is useful when you want to give users the option to leave a message even when no agents are available.

Examples

Check status before opening chat:

const status = HEYO.getAgentStatus();

if (status === 'online') {
    HEYO.open();
} else {
    alert('Our support team is currently offline. Please leave a message!');
    HEYO.open({ force: true }); // Open anyway to leave a message
}

Prompt users before opening offline chat:

const chatButton = document.getElementById('chat-button');

chatButton.onclick = () => {
    const status = HEYO.getAgentStatus();
    
    if (status === 'offline') {
        const confirmed = confirm(
            'Our agents are currently offline. Would you like to leave a message?'
        );
        
        if (confirmed) {
            HEYO.open({ force: true });
        }
    } else {
        HEYO.open();
    }
};