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);
});