Skip to main content

JavaScript SDK

The official JavaScript SDK for embedding Char AI widgets in web applications.

Installation

npm install @char-ai/widget

Quick Start

import { CharWidget } from '@char-ai/widget';

const widget = new CharWidget({
  apiKey: 'char_sk_live_...',
  containerId: 'chat-widget'
});

Configuration

OptionTypeDefaultDescription
apiKeystringrequiredYour site API key
containerIdstring'char-widget'Container element ID
theme'light' | 'dark' | 'auto''auto'Color theme
mode'embedded' | 'floating''floating'Display mode
position'bottom-right' | 'bottom-left''bottom-right'Position for floating mode
userobjectnullUser identification
colorsobject{}Custom color overrides

Methods

open()

Open the chat widget:
widget.open();

close()

Close the chat widget:
widget.close();

toggle()

Toggle the widget open/closed:
widget.toggle();

setUser(user)

Identify the current user:
widget.setUser({
  id: 'user_123',
  email: '[email protected]',
  name: 'John Doe',
  metadata: {
    plan: 'premium'
  }
});

sendMessage(message)

Programmatically send a message:
widget.sendMessage('Hello, I need help with my order');

destroy()

Remove the widget and clean up:
widget.destroy();

Events

Listen for widget events:
widget.on('open', () => {
  console.log('Widget opened');
});

widget.on('close', () => {
  console.log('Widget closed');
});

widget.on('message', (message) => {
  console.log('New message:', message);
});

widget.on('error', (error) => {
  console.error('Widget error:', error);
});

TypeScript

Full TypeScript support included:
import { CharWidget, CharWidgetConfig, Message } from '@char-ai/widget';

const config: CharWidgetConfig = {
  apiKey: 'char_sk_live_...',
  theme: 'dark'
};

const widget = new CharWidget(config);

widget.on('message', (message: Message) => {
  console.log(message.content);
});