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
npm install helpwrenUse
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
createWidget(appOrigin: string): HelpwrenWidgetappOrigin is your install's address. The returned object has the methods
of window.Helpwren:
| Method | Signature |
|---|---|
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
| Type | What it is |
|---|---|
InitOptions | The options of init. See Options |
Appearance | position, offsetX, offsetY, accent, accentTo, accentInk, launcher. See Appearance |
WidgetLayout | width, 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" } |
PageContext | Record<string, string | number | boolean | null>. See Context |
HelpwrenEvents | The 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
/embedpage in a frame. The page and the frame talk withpostMessage; 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.