Embedding reference

This reference is for developers who put the Helpin widget on a website or app. It lists the URLs to load, the origin rules the widget enforces, every supported script-tag attribute, and the support-only mode. For a first installation, follow Embed the widget. To control the widget from code, see the Widget SDK developer guide.

Hosts and runtime URLs

The SDK needs two URLs: the runtime (the lib.js script) and the host (the Helpin server the widget connects to).

Deployment	Runtime (src / widgetRuntimeUrl)	Host (data-host / host)
Helpin Cloud	https://cdn.helpin.ai/lib.js	https://client.helpin.ai
Self-hosted	<your public widget URL>/sdk/lib.js	Your installation's public widget URL

The npm package, @helpin-ai/sdk-js, is a thin, typed wrapper. In the browser, it loads the runtime from widgetRuntimeUrl, which defaults to the Cloud CDN. Widget updates therefore reach your site without a redeploy. On a self-hosted installation, set widgetRuntimeUrl to your own runtime URL, or use supportOnly: true, which loads the runtime from host automatically.

Allowed origins

The widget connects only from origins you allow. Set them in Settings → Chat widget, under Choose where your widget can connect.

• Enter one origin per line, such as https://www.example.com. Include the scheme and any non-default port. Don't add a path, a trailing slash, or a wildcard.

• Add each preview, staging, and local development origin separately, such as http://localhost:3000.

• For Tauri desktop apps, add tauri://localhost, http://tauri.localhost, or https://tauri.localhost, depending on the platform. Other Tauri apps share these origins, so also require server-signed identities.

• Allow all origins lets any website or desktop app connect, including apps that send no origin. Session and identity verification settings still apply.

• When origins are restricted and the list is empty, the widget is blocked for all visitors.

• You must add at least one origin before you can select Require server-signed identities.

The same rules apply to the widget's HTTP requests and its real-time connection. Published Help Center articles and the SDK script itself stay public. An origin allowlist limits browser embedding, but it doesn't prove who a visitor is. For that, use signed identities, which are described in the Widget SDK developer guide.

Script-tag attributes

Set these attributes on the <script src=".../lib.js"> tag. Boolean attributes take the values "true" or "false".

Attribute	npm option	Description
data-widget-key	widgetKey	Required. Your public widget key. data-key also works.
data-host	host	Helpin host URL. data-tracking-host also works.
data-namespace	namespace	Name of the global command function. Default: helpin.
data-auto-boot	autoBoot	Set "false" to keep the widget dormant until you call boot(), show(), open(), openMessages(), or openNewMessage().
data-auto-pageview	autoPageview	Track pageviews automatically, including single-page app navigation.
data-support-only	supportOnly	Chat and identification only. See the next section.
data-no-auto-init	none	Set "true" to skip automatic setup, then call helpin('init', { widgetKey, host }) yourself.
data-log-level	logLevel	Console logging: debug, info, warn, or error (default).
data-cross-domain-linking	crossDomainLinking	Set "false" to stop sharing the visitor ID across domains.
data-domains	domains	Comma-separated domains that share the visitor ID when links are clicked.
data-property-blacklist	propertyBlacklist	Comma-separated property names to leave out of events.
data-privacy-policy	privacyPolicy	Set "strict" to stop storing an anonymous visitor ID.
data-use-beacon-api	useBeaconApi	Send events with the Beacon API.
data-force-use-fetch	forceUseFetch	Send events with fetch.

The npm package also accepts widgetRuntimeUrl, cookieDomain, cookieName, formCapture, and interactionCaptureRules.

Support-only mode

Set supportOnly: true (or data-support-only="true") when you want the chat widget without Helpin analytics. In this mode, the SDK:

• loads the chat widget and supports visitor identification;

• doesn't start the analytics collector, automatic pageviews, form capture, or cross-domain linking;

• loads the runtime from host + /sdk/lib.js, unless you set widgetRuntimeUrl.

Support-only mode requires an explicit host.

Script tag or npm

	Script tag	npm package
Setup	Paste two <script> blocks	npm install @helpin-ai/sdk-js
API	helpin('method', ...args)	Typed HelpinClient object
Early calls	Queued until the SDK loads	Available once helpinClient(...) returns
Runtime updates	Loaded from the CDN	Loaded from widgetRuntimeUrl

Both options offer the same widget and analytics features. In frameworks that render on the server, such as Next.js, create the client in browser-only code. Vue, React, and Next.js apps can use @helpin-ai/vue, @helpin-ai/react, or @helpin-ai/nextjs, which wrap the npm package. See Framework packages.

Troubleshooting

• The widget doesn't appear. Check that the page's exact origin, including its port, is in the allowlist, and that the key and host match the same workspace.

• It works locally but not in preview. Each preview URL is its own origin. Add it to the allowlist.

• A self-hosted site loads the Cloud script. Set widgetRuntimeUrl, or change the src, to your installation's /sdk/lib.js.