Skip to Content
Docs
Packages

helpwren

Reference for the helpwren npm package, the widget for apps that bundle their own code.

The package and the script tag behave the same and share one set of types. A site with a script tag needs nothing from npm: every install serves the widget at /widget.js. The package has no dependencies and is about 6.5 kB gzipped.

Install

Terminal
npm install helpwren

Use

support.ts
import { createWidget } from "helpwren";

const chat = createWidget("https://support.example.com");
chat.init({ source: "web" });
chat.identify({ token: () => auth.getHelpwrenToken() });
chat.on("unread", (count) => setBadge(count));

createWidget

Signature
createWidget(appOrigin: string): HelpwrenWidget

appOrigin is your install's address. The returned object has the methods of window.Helpwren:

MethodSignature
init(options?: InitOptions) => void
show, hide, toggle() => void
isOpen() => boolean
startConversation(draft?: string) => void
identify(identity: Identity) => void
reset() => void
setContext(context: PageContext) => void
update(changes: { appearance?, layout? }) => void
on(event, listener) => () => void
destroy() => void

Types

TypeWhat it is
InitOptionsThe options of init. See Options
Appearanceposition, offsetX, offsetY, accent, accentTo, accentInk, launcher. See Appearance
WidgetLayoutwidth, height, zIndex
Identity{ token: string | (() => string | Promise<string>) }, or { id?, name?, email? } for unverified details
IdentityState{ state: "guest" }, { state: "user" } or { state: "failed", reason: "expired" | "rejected" | "off" | "error" }
PageContextRecord<string, string | number | boolean | null>. See Context
HelpwrenEventsThe events and their listeners

helpwren/protocol

helpwren/protocol holds the messages the page and the chat exchange, for a host that builds its own frame, such as a native app. See Other platforms.

How it works

  • The widget adds one element with a shadow root, so the site's CSS and the widget's cannot affect each other.
  • The chat is the install's /embed page in a frame. The page and the frame talk with postMessage; the widget listens only to its own frame on the install's origin, and the frame sends only to the page that answered it.
  • Which sites may show the chat is the install's allowed domains, enforced by the browser.

Its changes are listed in packages/widget/CHANGELOG.md.