Widget

#Installation

Add this script tag to your website, just before the closing </body> tag:

1
2
3
4
5
6
<script
  src="https://widget.customerhero.app/v1/loader.js"
  data-chatbot-id="YOUR_CHATBOT_ID"
  data-api-base="https://us.api.customerhero.app"
  async
></script>

Find your chatbot ID in the Embed tab of your chatbot settings. The script is lightweight (~15KB) and loads asynchronously, so it won't slow down your page.

The data-api-base attribute tells the widget which regional API host to call. CustomerHero stores each organization's data in one region (US or EU), and the widget must talk to that region's host. Use https://us.api.customerhero.app for US-region chatbots and https://eu.api.customerhero.app for EU-region chatbots. The dashboard's Embed tab generates the snippet with the correct value already filled in for your chatbot.

#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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<script
  src="https://widget.customerhero.app/v1/loader.js"
  data-chatbot-id="YOUR_CHATBOT_ID"
  data-api-base="https://us.api.customerhero.app"
  async
></script>
<script>
  window.CustomerHero = window.CustomerHero || { q: [] };
  CustomerHero.q.push(["identify", {
    userId: "user_12345",        // Required: stable unique ID from your system
    email: "jane@acme.com",      // Optional
    name: "Jane Smith",          // Optional
    phone: "+1234567890",        // Optional
    company: "Acme Corp",        // Optional
    plan: "pro",                 // Any custom properties
    accountAge: 365
  }]);
</script>

The command queue pattern ({ q: [] }) ensures commands are buffered if the widget script hasn't loaded yet, similar to analytics libraries. Once loaded, you can call CustomerHero.identify({ ... }) directly.

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
   CustomerHero.q.push(["identify", {
     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.