Customization

The Heapchat Web SDK provides extensive customization options to match your brand's look and feel. You can customize colors, themes, and widget behavior to create a seamless integration with your application.

Configuration Options

The SDK supports several configuration options to customize the widget behavior:

configuration.ts

import { Heapchat, Position } from 'heapchat';

Heapchat.configure({
  apiKey: 'your_api_key_here',
  position: Position.BOTTOM_RIGHT,  // or Position.BOTTOM_LEFT
  welcomeMessage: 'Hello! How can we help you today?' // Custom welcome message
});

Configuration Properties

Property	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
`welcomeMessage`	string	No	`How can we assist you today?`	Custom welcome message displayed to users

Theme Configuration

The SDK supports both light and dark themes with automatic system theme detection. You can customize colors for both themes independently.

Basic Theme Setup

theme-config.ts

import { Heapchat } from 'heapchat';

// Configure custom theme
Heapchat.setTheme({
  // Dark mode colors
  primaryColor: '#2563eb',
  primaryTextColor: '#f8fafc',
  secondaryColor: '#1e293b',
  secondaryTextColor: '#f1f5f9',
  backgroundColor: '#19191a',
  backgroundTextColor: '#f8fafc',
  borderColor: '#334155',
  borderTextColor: '#f1f5f9',
  iconColor: '#e2e8f0',
  iconTextColor: '#0f172a',
  headerColor: '#2563eb',
  headerIndicatorColor: '#48bb78',
  headerTextColor: '#f8fafc',
  destructive: '#ef4444',
  destructiveText: '#f8fafc',

  // Light mode colors
  primaryColorLight: '#2563eb',
  primaryTextColorLight: '#f8fafc',
  secondaryColorLight: '#f8fafc',
  secondaryTextColorLight: '#0f172a',
  backgroundColorLight: '#ffffff',
  backgroundTextColorLight: '#0f172a',
  borderColorLight: '#e2e8f0',
  borderTextColorLight: '#0f172a',
  iconColorLight: '#475569',
  iconTextColorLight: '#f8fafc',
  headerColorLight: '#2563eb',
  headerIndicatorColorLight: '#48bb78',
  headerTextColorLight: '#f8fafc',
  destructiveLight: '#ef4444',
  destructiveTextLight: '#f8fafc',
});

Color Properties

The theme configuration includes the following color properties for both dark and light modes:

Property	Description	Usage
`primaryColor`	Main brand color	Buttons, links, active states
`primaryTextColor`	Text color on primary background	Button text, header text
`secondaryColor`	Secondary background color	Sidebar, secondary buttons
`secondaryTextColor`	Text color on secondary background	Secondary text
`backgroundColor`	Main background color	Chat container background
`backgroundTextColor`	Text color on main background	Main text content
`borderColor`	Border color	Dividers, input borders
`borderTextColor`	Text color on borders	Placeholder text
`iconColor`	Icon background color	Icon containers
`iconTextColor`	Icon color	Icon fill color
`headerColor`	Header background color	Chat header background
`headerIndicatorColor`	Online indicator color	Status indicator
`headerTextColor`	Header text color	Header text
`destructive`	Error/danger color	Delete buttons, error states
`destructiveText`	Text color on destructive background	Error text

Theme Modes

The SDK supports three theme modes:

theme-modes.ts

import { Heapchat } from 'heapchat';

// Set theme mode
Heapchat.setThemeMode('light');    // Force light theme
Heapchat.setThemeMode('dark');     // Force dark theme
Heapchat.setThemeMode('system');   // Follow system preference (default)

Customize the widget position on your page:

positioning.ts

import { Heapchat, Position } from 'heapchat';

// Configure widget position
Heapchat.configure({
  apiKey: 'your_api_key_here',
  position: Position.BOTTOM_RIGHT  // or Position.BOTTOM_LEFT
});

Welcome Message Customization

You can set a custom welcome message that will be displayed to users when they first open the chat:

welcome-message.ts

import { Heapchat } from 'heapchat';

// Set custom welcome message during configuration
Heapchat.configure({
  apiKey: 'your_api_key_here',
  welcomeMessage: '👋 Welcome! How can we assist you today?'
});

Advanced Customization

Toggle Button Visibility

Control whether the toggle button is visible:

toggle-button.ts

import { Heapchat } from 'heapchat';

Heapchat.configure({
  apiKey: 'your_api_key_here'
});

// Or control it dynamically
Heapchat.showToggleButton();  // Show the button
Heapchat.hideToggleButton();  // Hide the button

Integration Examples

customized-chat.tsx

"use client";

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

function CustomizedHeapchat() {
    useEffect(() => {
        // Configure the SDK with all options
        Heapchat.configure({
            apiKey: 'your_api_key_here',
            position: 'BOTTOM_RIGHT',
            welcomeMessage: '👋 Welcome! How can we help you today?'
        });

        // Set custom theme
        Heapchat.setTheme({
            primaryColor: '#6366f1', // Indigo
            primaryTextColor: '#ffffff',
            backgroundColor: '#0f172a', // Slate 900
            backgroundTextColor: '#f8fafc',
            headerColor: '#6366f1',
            headerIndicatorColor: '#10b981', // Emerald 500
            // ... other colors
        });

        // Set theme mode
        Heapchat.setThemeMode('system');

        return () => {
            Heapchat.destroy();
        };
    }, []);

    return null;
}

export default CustomizedHeapchat;

Web Customization