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,
});

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

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.

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>

<!-- 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.