Web Setup
Learn how to set up and integrate the Heapchat SDK into your web application
Installation
bun add heapchatpnpm add heapchatnpm install heapchatyarn add heapchatInitialize the SDK
Initialize the SDK with your API key. You can find your API key in the Heapchat dashboard.
import { Heapchat } from 'heapchat';
// Configure the widget
Heapchat.configure({
apiKey: 'your_api_key_here'
});"use client";
import { useEffect } from "react";
import { Heapchat } from "heapchat";
function HeapchatSDK() {
useEffect(() => {
Heapchat.configure({
apiKey: 'your_api_key_here'
});
return () => {
Heapchat.destroy();
};
}, []);
return null;
}
export default HeapchatSDK;Add this to your main component (e.g. App.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
Login
Heapchat.login('user_id');Logout
Heapchat.logout();Customer Data
Set customer information for better support context:
Heapchat.setCustomerData({
name: 'John Doe',
email: 'john@example.com',
phone: '+1234567890'
});Widget Controls
Show Widget
Heapchat.show();Hide Widget
Heapchat.hide();Destroy Widget
Heapchat.destroy();Widget Behavior
- The widget initializes with a floating action button (FAB) in the configured position
- Clicking the FAB toggles the chat widget visibility
- The widget appears with a smooth animation
- The widget is responsive and works well on both desktop and mobile devices
TypeScript Support
The SDK is written in TypeScript and provides full type definitions. Key interfaces include:
import { Position } from 'heapchat';
type HeapchatConfig = {
apiKey: string;
position?: Position.BOTTOM_RIGHT | Position.BOTTOM_LEFT;
}
type CustomerDataModel = {
name?: string;
email?: string;
phone?: string;
}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
- Clean up resources by calling
destroy()when the chat widget is no longer needed