Web Setup

Installation

bun add heapchat

pnpm add heapchat

npm install heapchat

yarn add heapchat

Initialize the SDK

Initialize the SDK with your API key. You can find your API key in the Heapchat dashboard.

heapchatSDK.tsx

"use client";

import { useEffect } from "react";
import { Heapchat } from "heapchat";

function HeapchatSDK() {
    useEffect(() => {
        Heapchat.configure({
            apiKey: 'your_api_key_here'
        });
    }, []);

    return null;
}

export default HeapchatSDK;

index.js

import { Heapchat } from 'heapchat';

// Configure the widget
Heapchat.configure({
  apiKey: 'your_api_key_here'
});

Add this to your main component (e.g. App.tsx, Layout.tsx)

layout.tsx

import HeapchatSDK from './heapchatSDK';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        <HeapchatSDK />
        {children}
      </body>
    </html>
  );
}

Configuration

The SDK uses a singleton pattern, meaning you'll always work with the same instance across your application. The configuration accepts the following options:

Option	Type	Required	Default	Description
`apiKey`	string	Yes	-	Your Heapchat API key
`position`	`Position.BOTTOM_RIGHT` \| `Position.BOTTOM_LEFT`	No	`Position.BOTTOM_RIGHT`	Position of the chat widget.

API Reference

User Authentication

Heapchat.login('user_id');

Logout

Heapchat.logout();

Customer Data

Set customer information for better support context:

index.ts

Heapchat.setCustomerData({
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890'
});

You can also pass extra custom data (as a JavaScript object/HashMap) for each user. This is useful for storing additional attributes such as user preferences, account type, or any metadata you want to associate with the customer.

Use the setCustomerCustomData method after logging in the user:

Example: Passing custom data in the Web SDK

import { Heapchat } from 'heapchat';

// ... after Heapchat.configure and Heapchat.login

const customData = {
  accountType: 'premium',
  referralCode: 'REF12345',
};

Heapchat.setCustomerCustomData(customData);

Best Practices

Configure the SDK as early as possible in your application lifecycle
Set customer data when available to provide context for support agents
Handle user authentication state changes by calling appropriate login/logout methods