Docs

Initialization Options

Configure advanced options when loading the Heyo widget.

When using the JS SDK, you can pass additional options to the init() function to control how the widget loads.

Available options

You can pass these options when initializing Heyo:

// Use either import style
import { HEYO } from '@heyo.so/js'; // or: import HEYO from '@heyo.so/js'

HEYO.init({
    projectId: 'YOUR_PROJECT_ID',
    hidden: true,
    loadMode: 'lazy',
    widgetStyle: 'bubble',
});

projectId

string

Your project ID. Required for localhost development, optional in production.

hidden

boolean

Start with the widget hidden. You can show it later with HEYO.show(). Default is false

logs

string

Control the logging level for debug purposes. Options: debug, minimal, or none. Default is minimal

loadMode

'eager' | 'lazy'

Choose when HEYO starts loading. eager starts immediately. lazy waits until the host page has loaded and the browser is idle. A command or live-status request starts it sooner when needed. Default is eager

widgetStyle

'bubble' | 'agent-card'

Override the project's launcher style on this page.

widgetPosition

'left' | 'right'

Override the project's launcher position on this page.

widgetSize

'small' | 'medium' | 'large'

Override the project's launcher size on this page.

widgetColor

string

Override the project's launcher color on this page.

Project ID

The projectId is essential for development:

HEYO.init({
    projectId: '665b12a3b4c5d6e7f8g9h0i1',
});

In production, Heyo can often detect your project automatically from your domain. However, it's good practice to always include the projectId for consistency.

Hidden by default

Sometimes you want to load the widget but not show it immediately:

HEYO.init({
    projectId: 'YOUR_PROJECT_ID',
    hidden: true,
});

// Show it later when needed
setTimeout(() => {
    HEYO.show();
}, 5000);

Logging levels

Control the amount of debug information shown in the browser console:

HEYO.init({
    projectId: 'YOUR_PROJECT_ID',
    logs: 'debug', // Options: 'debug', 'minimal', 'none'
});

debug: Shows all debug messages, useful for development
minimal: Shows only important messages (default)
none: Suppresses all console messages

This is particularly helpful when debugging integration issues during development.

Chat loading mode

Use lazy on performance-sensitive pages so the full chat app does not compete with the host page's initial loading work:

HEYO.init({
    projectId: 'YOUR_PROJECT_ID',
    loadMode: 'lazy',
});

When used through the JS SDK, no Heyo script is injected before the host page fires load. Heyo then starts during browser idle time and initializes the configured launcher and chat. A command or live-status request made first starts loading immediately. Local reads such as isOpen() keep their synchronous fallback without starting a network request. Bubble and agent-card launchers, returning visitors, and hideWhenOffline all follow the same page-load boundary.

HTML Script Attributes

If you're using the HTML script tag instead of the JS SDK, you can set these options as data attributes:

<!-- Hidden by default -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-hidden="true"></script>

<!-- With debug logging -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-logs="debug"></script>

<!-- Preload the chat after page load during idle time -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-load-mode="lazy"></script>

<!-- Multiple options -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-hidden="true" data-logs="none"></script>

Real-World Examples

Show widget only to logged-in users:

// Initialize but keep hidden
HEYO.init({
    projectId: 'YOUR_PROJECT_ID',
    hidden: true,
});

// Check authentication
if (user.isAuthenticated) {
    HEYO.show();
    HEYO.identify({
        userId: user.id,
        email: user.email,
        name: user.name,
    });
}

Different behavior for development vs production:

const isDevelopment = window.location.hostname === 'localhost';

HEYO.init({
    projectId: isDevelopment ? 'YOUR_PROJECT_ID' : undefined,
    hidden: isDevelopment, // Hide in development
});

Tip: The hidden option is great for controlling when the widget appears based on user actions, page type, or authentication status.

That's all the initialization options available. Use them to fine-tune how and when Heyo loads on your site.

Customizing Appearance

Change the widget style, color, size and position to match your brand.

Agent Status

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