Widget

#Installation

Install both the React bindings and the underlying JS client:

1
npm install @customerhero/react @customerhero/js

The fastest way to add a chatbot is the drop-in ChatWidget component:

1
2
3
4
5
6
7
8
9
10
import { ChatWidget } from "@customerhero/react";

export default function App() {
  return (
    <>
      {/* Your app content */}
      <ChatWidget chatbotId="YOUR_CHATBOT_ID" />
    </>
  );
}

All configuration from the dashboard is fetched automatically. You can also override options via props:

1
2
3
4
5
6
7
8
9
10
<ChatWidget
  chatbotId="YOUR_CHATBOT_ID"
  primaryColor="#0066FF"
  position="bottom-left"
  welcomeMessage="Hey! How can we help?"
  suggestedMessages={[
    "What can you help me with?",
    "How does pricing work?",
  ]}
/>

#Customization

Customize the widget appearance from the Customize tab in your chatbot settings. Options include:

• Primary color — The main accent color for the widget header and buttons
• Position — Bottom-right (default) or bottom-left
• Welcome message — The first message visitors see when they open the chat
• Bot name & avatar — Shown in the chat header

#Customer identity

On pages where your users are logged in, you can pass their identity to the widget so conversations are linked to customer records in your inbox.

Pass an identity prop to the ChatWidget component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { ChatWidget } from "@customerhero/react";

function App({ user }) {
  return (
    <ChatWidget
      chatbotId="YOUR_CHATBOT_ID"
      identity={user ? {
        userId: user.id,          // Required: stable unique ID
        email: user.email,        // Optional
        name: user.name,          // Optional
        plan: user.plan,          // Custom property
        accountAge: 365,          // Custom property
      } : undefined}
    />
  );
}

When the identity prop changes, the widget clears the current conversation and starts a fresh one for the identified user.

The userId must be a stable, unique identifier from your system (e.g. a database ID). When the same userId appears from a different browser, the conversation is linked to the same customer record.

Standard fields like email, name, phone, and company are stored as first-class customer fields. Any additional properties (like plan above) are saved as custom metadata.

#Identity verification (HMAC)

To prevent users from impersonating others by guessing a userId, you can enable HMAC-based identity verification. This is optional but recommended for production.

1. Go to your chatbot's Customize page and generate an identity verification secret in the Identity Verification section.
2. On your server, compute an HMAC-SHA256 of the user's ID using the secret:

   1
   2
   3
   4
   5
   const crypto = require("crypto");
   const userHash = crypto
     .createHmac("sha256", "YOUR_IDENTITY_SECRET")
     .update(userId)
     .digest("hex");

3. Pass the userHash alongside the userId:

   1
   2
   3
   4
   5
   6
   7
   8
   <ChatWidget
     chatbotId="YOUR_CHATBOT_ID"
     identity={{
       userId: "user_12345",
       email: "jane@acme.com",
       userHash: "a1b2c3d4...", // HMAC-SHA256 computed server-side
     }}
   />

When a chatbot has an identity secret configured and a userHash is provided, the server verifies the HMAC before trusting the identity. If verification fails, the request is rejected with a 403 error.

#Content Security Policy (CSP)

If your site uses a Content Security Policy, add these directives:

1
2
3
script-src 'self' https://widget.customerhero.app;
connect-src 'self' https://api.customerhero.app;
frame-src 'self' https://widget.customerhero.app;

Without these, the browser will block the widget script and API requests.