Helpin
Dark mode
Embed the widget

Embed the widget

Installing the Helpin chat widget takes one script tag or one npm package. This page is the full reference for both methods, plus the programmatic API.

Get your widget key

  1. Go to Settings → Chat Widget.

  2. In Widget Installation, copy your widget key (or generate one if none exists).

  3. The installation snippet below uses this key.

The widget key is public (it appears in your site's HTML). Regenerating it invalidates the old one — only do this if the key leaked.

Option A: Script tag (HTML / JS)

Paste this before the closing </body> tag:

<script>
  window.helpinQ = window.helpinQ || [];
  window.helpin = function () {
    window.helpinQ.push(arguments);
  };

  helpin('onLoad', function () {
    helpin('track', 'pageview');
  });
</script>

<script
  defer
  src="https://cdn.helpin.ai/lib.js"
  data-widget-key="your-widget-key"
  data-host="https://client.helpin.ai"
  data-namespace="helpin"
></script>

The snippet queues commands until the SDK loads, so you can call helpin(...) immediately. Script-tag equivalents of the module options: data-widget-key, data-host, data-auto-boot, data-namespace, data-auto-pageview, data-log-level.

Option B: React

npm install @helpin-ai/sdk-js
import { helpinClient } from '@helpin-ai/sdk-js';

const client = helpinClient({
  widgetKey: 'your-widget-key',
  host: 'https://client.helpin.ai',
});

Place this at your application root so the widget mounts once. The npm module is a typed wrapper: in the browser it loads the same hosted runtime from https://cdn.helpin.ai/lib.js, so widget UI updates ship from the CDN without redeploys.

For a context provider and a useHelpin() hook, use @helpin-ai/react instead. See Framework packages in the Widget SDK developer guide.

Option C: Vue

Install @helpin-ai/vue and register HelpinPlugin when you create your app. It delegates to the same hosted runtime.

npm install @helpin-ai/vue @helpin-ai/sdk-js
import { createClient, HelpinPlugin } from '@helpin-ai/vue';

const client = createClient({
  widgetKey: 'your-widget-key',
  host: 'https://client.helpin.ai',
});

createApp(App).use(HelpinPlugin, { client }).mount('#app');

In components, call useHelpin() to get the widget and analytics methods. See Framework packages in the Widget SDK developer guide for details, including Nuxt.

Option D: Next.js

Initialize Helpin from a Client Component so server rendering stays safe:

'use client';
import { useEffect } from 'react';
import { helpinClient } from '@helpin-ai/sdk-js';

export function HelpinWidget() {
  useEffect(() => {
    helpinClient({ widgetKey: 'your-widget-key', host: 'https://client.helpin.ai' });
  }, []);
  return null;
}

Mount it in your root layout. For a provider and a useHelpin() hook, use @helpin-ai/nextjs, described under Framework packages in the Widget SDK developer guide. The settings page's Install with AI tab generates a copy-paste prompt you can hand to an AI coding tool to do the integration for you.

Configuration options

Option

Description

widgetKey

Required. Your public widget key.

host

Helpin host URL, with or without protocol.

autoBoot

Boot the widget on initialization (default true). Set false to keep it dormant until you call boot(), open(), etc.

namespace

Global name for the script-tag build (default helpin).

widgetRuntimeUrl

Override the hosted runtime URL (staging or pinned deployments).

autoPageview

Track a pageview automatically on load.

cookieDomain / cookieName

Customize the anonymous visitor ID cookie.

crossDomainLinking / domains

Share the visitor ID across specified domains.

propertyBlacklist

Omit specific fields from outgoing payloads.

logLevel

Internal logging verbosity.

Client API

Widget control

Method

Description

boot(settings?)

Boot or re-boot the widget.

show() / hide()

Show or hide the launcher (hide also closes the panel).

open() / close() / toggle()

Open, close, or toggle the chat panel.

openMessages()

Open the widget to the messages list.

openNewMessage(content?)

Start a new conversation, optionally pre-filled.

openConversation(id)

Open a specific conversation.

openArticle(articleKey, options?)

Open a help-center article inside the widget.

shutdown()

End the widget session and remove it from the page.

Analytics

Method

Description

id(userData)

Identify a logged-in user (email, name, company).

lead(payload)

Track a validated lead event.

track(name, payload?)

Track a custom event.

group(company)

Associate the user with a company.

pageview()

Send a pageview.

set(props) / unset(name)

Attach or remove properties.

reset()

Clear persisted user, company, and global state.

Event listeners

onOpen, onClose, onUnreadCountChange, onUserEmailSupplied, onConversationStarted, onMessageReceived — register callbacks for widget-driven events.

Getters

getVisitorId(), isWidgetReady(), getConfig(), getLogger(), getCookie(name).

Open an article from your own UI

Pass the final article segment from its Helpin URL:

// https://acme.helpin.center/articles/getting-started-1a2b3c4d
client.openArticle('getting-started-1a2b3c4d');

Optionally scope it with { collectionId, spaceId }. If you are migrating from another help-center provider, map the old article ID to the Helpin article key, or fall back to a normal link.

Troubleshooting

  • Widget does not appear — verify widgetKey and host, and that the key belongs to the in-app widget (a public help center may intentionally use a different key).

  • Commands run too early — calls are queued; with a script tag, register startup work via helpin('onLoad', callback).

  • Custom launcher controls startup — set autoBoot: false, then call open(), openNewMessage(), or openArticle().

  • Article does not open — pass the final URL segment, not the full URL or a legacy article ID.

Was this article helpful?