JavaScript Integration

For applications not using React, you can integrate the Helper Chat Widget using vanilla JavaScript. This approach requires both backend and frontend components to ensure secure authentication.

Backend Setup

First, you'll need to generate an HMAC hash on your server to authenticate the widget.

Store Your HMAC Secret

Securely store your HMAC secret in your server environment. This secret should never be exposed to the client.

Generate HMAC Hash

When a user is authenticated in your application, generate an HMAC hash using their email and the current timestamp:

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"

This hash, along with the email and timestamp, will be passed to the frontend to initialize the widget.

Frontend Setup

Basic Implementation

Add the following script to your HTML, replacing the placeholder values with the actual values from your backend:

<script>
  (function(d,t) {
    var g=d.createElement("script");
    g.src="https://helper.ai/widget/sdk.js";
    g.onload=function(){
      window.HelperWidget.init({
        email: "CUSTOMER_EMAIL", // This is the email address of your authenticated customer
        email_hash: "GENERATED_HMAC_FROM_SERVER", // This is the HMAC you generated from the server
        mailbox_slug: "YOUR_MAILBOX_SLUG", // This is your mailbox slug
        timestamp: TIMESTAMP, // Same timestamp as the one used to generate the HMAC in the server
        title: "Support", // You can customize the title of the chat widget (optional)
        metadata: { // Add additional customer information to Helper
          value: "CUSTOMER_VALUE", // Revenue value of the customer (optional)
          name: "CUSTOMER_NAME", // Name of the customer (optional)
          links: {"Impersonate": "https://example.com/impersonate", "Dashboard": "https://example.com/dashboard"}, // Links of the customer (optional)
        },
      })
    }
    d.body.appendChild(g);
  })(document);
</script>

Advanced Usage

You can programmatically show, hide, or toggle the chat widget:

// Show the chat widget
window.HelperWidget.show();
 
// Hide the chat widget
window.HelperWidget.hide();
 
// Toggle the chat widget visibility
window.HelperWidget.toggle();

Adding 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>

Configuration Options

The init method accepts the following options:

Option	Type	Required	Description
`email`	string	Yes	Email address of the authenticated customer
`email_hash`	string	Yes	HMAC hash generated on the server
`mailbox_slug`	string	Yes	Your mailbox slug from Helper dashboard
`timestamp`	number	Yes	Timestamp used in HMAC generation
`title`	string	No	Custom title for the chat widget
`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

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