threadhive-widget

Official loader for the ThreadHive chat widget — AI-powered support chat for any web app.

npm install threadhive-widget

Quick start

import { init } from "threadhive-widget";

init({ widgetKey: "wk_your_key" }); // Dashboard → Chatbot → Install

That's it — the launcher appears bottom-right, AI answers from your help center, and hands off to your team when unsure.

React / Next.js

"use client";
import { useEffect } from "react";
import { init } from "threadhive-widget";

export function ThreadHiveProvider() {
  useEffect(() => {
    init({ widgetKey: process.env.NEXT_PUBLIC_THREADHIVE_KEY! });
  }, []);
  return null;
}

SSR-safe: every call is a no-op on the server.

Identify signed-in users

import { identify, reset } from "threadhive-widget";

// After login. Compute userHash server-side:
//   HMAC_SHA256(userId, your_identity_secret)
identify({ userId: "u_123", email: "[email protected]", name: "Ada" }, userHash);

// On logout:
reset();

Track events

import { track, page, getVisitorId } from "threadhive-widget";

track("plan_upgraded", { plan: "pro" });
page(); // manual pageview (SPA route changes are auto-tracked)
getVisitorId(); // anonymous visitor id, once loaded

Self-hosted ThreadHive

init({ widgetKey: "wk_…", origin: "https://your-domain.com/api" });

API

| Function | Description | | --- | --- | | init(options) | Load the widget. Idempotent; returns a promise. | | identify(traits, userHash?) | Link the visitor to a user. userId required. | | track(name, props?) | Record a custom event. | | page(props?) | Record a pageview. | | reset() | Forget the visitor (logout). | | getVisitorId() | Anonymous visitor id. |

Calls made before init() resolves are queued and flushed automatically.

License

MIT © ThreadHive — [email protected]

1.0.1 release notes

• Preserve queued identity calls while the widget script is loading.
• Keep existing widget settings when initializing the loader.
• Allow retrying failed loads and reject accidental workspace switching.

Update an existing installation with npm install threadhive-widget@latest, then rebuild and deploy your application. The hosted chat UI updates independently of this loader package.

Keeping contacts consistent

Initialize once per page and call identify() after your application loads the signed-in user, including on public pages where a session exists. Use the same stable database user ID on every visit and device. Calls made while the loader is starting are queued.

Call reset() only when the person logs out or switches accounts, not on route changes, opening the widget, or closing a conversation. Anonymous visitors retain a browser ID until storage is cleared; separate browsers cannot be recognized as the same person until your application identifies them. A typed name or unverified email alone is not proof that two visitors are the same person.