@customerhero/js

Framework-agnostic JavaScript client for the CustomerHero chat widget. Use this package directly in vanilla JS / TS apps, or via the React bindings in @customerhero/react.

Install

npm install @customerhero/js

Quick start

import { CustomerHeroChat } from "@customerhero/js";

const chat = new CustomerHeroChat({
  chatbotId: "bot_xxxxxxxxxxxxxxxxxxxx",
});

chat.subscribe((state) => {
  // React to state changes — messages, open/closed, loading, etc.
});

chat.open();
await chat.sendMessage("Hello!");

Identify a signed-in user

Link conversations to a user in your system by calling identify as soon as you know who the user is.

chat.identify({
  userId: "usr_123",
  email: "[email protected]",
  name: "Jane Doe",
  // Optional HMAC for identity verification (recommended in production)
  userHash: "<hmac-sha256(userId, secret)>",
});

Configuration

| Option | Type | Description | | ------------------- | --------------------------------- | --------------------------------------------------------------------------- | | chatbotId | string (required) | The chatbot to connect to. | | apiBase | string | API base URL. Defaults to https://api.customerhero.app. | | primaryColor | string | Accent color override. | | backgroundColor | string | Chat window background override. | | textColor | string | Text color override. | | position | "bottom-right" \| "bottom-left" | Widget position. | | placeholderText | string | Input placeholder override. | | welcomeMessage | string | Welcome message override. | | title | string | Header title override. | | avatarUrl | string | Bot avatar URL override. | | locale | string | Widget locale (e.g. "en", "es"). Auto-detected from browser if omitted. | | suggestedMessages | string[] | Quick-reply options shown before the first message. |

Appearance

| Option | Type | Description | | ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- | | colorScheme | "auto" \| "light" \| "dark" | auto follows the visitor's OS preference. Defaults to light. | | primaryColorDark | string | Primary color used in dark mode. Only honoured when the effective scheme is dark. | | backgroundColorDark | string | Background color used in dark mode. | | textColorDark | string | Text color used in dark mode. | | size | "compact" \| "default" \| "large" | Launcher diameter, panel dimensions, and base font size. | | cornerStyle | "soft" \| "rounded" \| "square" | Panel border-radius preset. | | launcher.iconUrl | string | Custom launcher icon URL (replaces the default chat-bubble glyph). | | launcher.label | string | CTA label next to the launcher (turns the bubble into a pill). Max 60 chars. | | launcher.showOnlineDot | boolean | Show a small green dot on the launcher when agents are available. | | offset.bottom | number | Pixel offset from the bottom edge. 0–1000. Defaults to 20. | | offset.side | number | Pixel offset from the side (mirrors position). 0–1000. Defaults to 20. | | zIndex | number | Z-index override. Defaults to 99999. Capped at 2 000 000 000. |

Dark colors are never auto-derived from primaryColor/backgroundColor/textColor — set them explicitly when enabling dark or auto modes.

License

MIT