JavaScript Integration

If you use React, please refer to the React integration guide.

Get Started

Add the following script to your HTML, replacing the placeholder values with your mailbox slug:

<script src="https://helper.ai/widget/sdk.js" data-mailbox="YOUR_MAILBOX_SLUG" async></script>

This is the simplest way to add the widget to your site. The widget will appear in the bottom-right corner of your page.

Optional: Next Steps

You can customize the widget by adding a helperWidgetConfig object above the widget script tag:

<script>
  window.helperWidgetConfig = {
    title: "My Helper Widget",
    icon_color: "#ff0000",
    show_toggle_button: true,
  };
</script>
<!-- The script you added earlier -->
<script src="https://helper.ai/widget/sdk.js" data-mailbox="YOUR_MAILBOX_SLUG" async></script>

The helperWidgetConfig object accepts the following options:

Option	Type	Required	Description
`title`	string	No	Custom title for the chat widget
`icon_color`	string	No	A custom color for the widget icon
`show_toggle_button`	boolean	No	Override the "Chat Icon Visibility" setting
`email`	string	Yes*	Email address of the authenticated customer
`email_hash`	string	Yes*	HMAC hash generated on the server
`timestamp`	number	Yes*	Timestamp used in HMAC generation
`metadata.value`	number	No	Revenue value of the customer
`metadata.name`	string	No	Name of the customer
`metadata.links`	object	No	Key-value pairs of links related to the customer

* Required only if you want to authenticate users

Add Contextual Help Buttons

You can add context-specific help buttons using HTML data attributes:

<!-- Open the chat with a specific prompt -->
<button data-helper-prompt="How do I change my plan?">Get help with plans</button>
 
<!-- Toggle the chat widget visibility -->
<button data-helper-toggle>Open chat</button>

Authenticate Your Users

To authenticate your users, you'll need to set up both backend and frontend components.

Backend Setup

First, generate an HMAC hash on your server using the HMAC secret from your Helper dashboard. Node.js example:

const crypto = require("crypto");
 
const hmacSecret = "YOUR_HMAC_SECRET"; // This is the HMAC secret from your Helper dashboard
const email = "customer@example.com"; // This is the email address of your authenticated customer
const timestamp = Date.now(); // This is the current timestamp in milliseconds
 
const hmac = crypto.createHmac("sha256", hmacSecret).update(`${email}:${timestamp}`).digest("hex"); // Format of content is "email:timestamp"

Frontend Setup

Add the generated HMAC hash, customer email, and timestamp to your widget config:

<script>
  window.helperWidgetConfig = {
    // ... any existing config ...
    email: "customer@example.com",
    email_hash: "GENERATED_HMAC",
    timestamp: GENERATED_TIMESTAMP_IN_MILLISECONDS,
  };
</script>
<!-- The script you added earlier -->
<script src="https://helper.ai/widget/sdk.js" data-mailbox="YOUR_MAILBOX_SLUG" async></script>

Optionally, you can add metadata to give Helper more context about the customer:

<script>
  window.helperWidgetConfig = {
    // ... existing config ...
    metadata: {
      name: "John Doe", // Optional: Customer name
      value: 1000, // Optional: Value of the customer for sorting tickets and VIP support
      links: {
        Profile: "https://example.com/profile", // Optional: Links to show in Helper alongside conversations from this customer
      },
    },
  };
</script>
<!-- The script you added earlier -->
<script src="https://helper.ai/widget/sdk.js" data-mailbox="YOUR_MAILBOX_SLUG" async></script>

Security Considerations

Never expose your HMAC secret on the client side
Always generate the HMAC hash on your server
Use HTTPS to prevent man-in-the-middle attacks
Validate the timestamp on your server to prevent replay attacks