React/Next.js Integration

The @helperai/react package provides first-class support for integrating the Helper Chat Widget into your React or Next.js applications. This integration offers a more seamless developer experience with TypeScript support and React hooks.

Installation

Install the package using npm:

npm install @helperai/react

Setup

Add Environment Variables

Add your Helper authentication credentials to your environment variables:

HELPER_HMAC_SECRET=your_hmac_secret
HELPER_MAILBOX_SLUG=your_mailbox_slug

For local development, add these to your environment file (e.g., .env.local), and for production, add them to your deployment environment.

Set Up the Provider

Add the HelperProvider to your root layout:

// app/layout.tsx or similar
import { HelperProvider, generateHelperAuth } from '@helperai/react';
 
export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const session = await auth(); // Your auth solution
  if (!session?.user?.email) return children;
 
  const helperAuth = await generateHelperAuth({
    email: session.user.email,
    metadata: {
      value: "CUSTOMER_VALUE", // Optional: Revenue value
      name: "CUSTOMER_NAME",   // Optional: Customer name
      links: {
        "Profile": "https://example.com/profile"
      }
    }
  });
  
  return (
    <html>
      <body>
        <HelperProvider {...helperAuth}>
          {children}
        </HelperProvider>
      </body>
    </html>
  );
}

Basic Usage

Use the useHelper hook in your components to interact with the chat widget:

import { useHelper } from '@helperai/react';
 
export function SupportButton() {
  const { show, sendPrompt } = useHelper();
  
  return (
    <button onClick={() => {
      sendPrompt('How do I change my plan?');
    }}>
      Get Help
    </button>
  );
}

Advanced Usage

import { useHelper } from '@helperai/react';
 
function ChatControls() {
  const { show, hide, toggle } = useHelper();
  
  return (
    <div>
      <button onClick={show}>Show Chat</button>
      <button onClick={hide}>Hide Chat</button>
      <button onClick={toggle}>Toggle Chat</button>
    </div>
  );
}

Adding Contextual Help Buttons

Create context-specific help buttons that open the chat with predefined prompts:

import { useHelper } from '@helperai/react';
 
function HelpButton({ prompt }: { prompt: string }) {
  const { show, sendPrompt } = useHelper();
  
  return (
    <button onClick={() => {
      sendPrompt(prompt);
    }}>
      Get Help
    </button>
  );
}

Example usage:

<HelpButton prompt="How do I update my billing information?" />

Metadata Options

The generateHelperAuth function accepts the following metadata options:

Option	Type	Description
`value`	number	Revenue value of the customer
`name`	string	Name of the customer
`links`	object	Key-value pairs of links related to the customer

Example:

const helperAuth = await generateHelperAuth({
  email: user.email,
  metadata: {
    value: 500, // Customer value in your currency
    name: "Jane Smith",
    links: {
      "Profile": "https://example.com/users/jane",
      "Billing": "https://example.com/users/jane/billing",
      "Orders": "https://example.com/users/jane/orders"
    }
  }
});