Widget JavaScript SDK Reference

Widget JavaScript SDK Reference

The Helpium widget is a self-contained JavaScript application that you embed on your website. It provides live chat, AI-powered search, and knowledge base access.

Installation

Add the following script to your website, just before the closing </body> tag:

<script>
(function() {
    var s = document.createElement('script');
    s.src = 'https://your-workspace.helpium.io/widget/helpium-widget.js';
    s.async = true;
    s.onload = function() {
        Helpium.init({
            apiKey: 'your_widget_key_here',
        });
    };
    document.head.appendChild(s);
})();
</script>

Helpium.init(options)

Initializes the widget. Must be called before any other method.

Options:

Option	Type	Description
apiKey	string	Required. Your workspace widget key
baseUrl	string	Custom API base URL (for self-hosted)
primaryColor	string	Hex color for the widget theme
contrastColor	string	Hex color for text on primary color
backgroundColor	string	Hex color for widget background
backgroundColorSecondary	string	Hex color for secondary surfaces
borderColor	string	Hex color for borders
textColor	string	Hex color for primary text
textColorSecondary	string	Hex color for secondary text

Helpium.identify(customer)

Identifies the current user for personalized support. Call this after your user logs in.

Helpium.identify({
    email: 'jane@example.com',
    name: 'Jane Smith',
    id: 'user_123',
    bearerToken: 'sanctum_token_here',
    avatarUrl: 'https://example.com/avatar.jpg',
    metadata: {
        company: 'Acme Corp',
        role: 'Admin',
        plan: 'Pro',
    }
});

Parameters:

Parameter	Type	Description
email	string	Required. Customer's email address
name	string	Customer's display name
id	string	Your internal user ID
bearerToken	string	Sanctum token for authenticated AI Actions
avatarUrl	string	URL to customer's avatar image
metadata	object	Custom key-value pairs shown to agents

Style Isolation

The widget uses Shadow DOM for complete style isolation. Your website's CSS will not affect the widget, and the widget's styles will not leak into your page.

WebSocket Connection

The widget automatically establishes a WebSocket connection for real-time messaging. No additional configuration is needed — connection details are fetched from the widget settings endpoint.

Single Page Applications (SPAs)

For SPAs like React, Vue, or Angular apps, call Helpium.init() once when your app mounts. The widget persists across client-side route changes. Call Helpium.identify() after authentication completes.