IllumiChat - AI-Powered Chat Platform

The IllumiChat Widget SDK provides a JavaScript API for creating, controlling, and responding to widget events programmatically.

The SDK always opens the production AI-first widget. There is no public version selector or conversation-start mode. Existing embed URLs and SDK initialization calls continue to work with the production renderer.

Global API

The main widget class. Create an instance by passing a configuration object.

const widget = new IllumiChat.Widget({
  assistantId: 'YOUR_ASSISTANT_ID'
});
await widget.initialize();

IllumiChat.getInstance()

Returns the current singleton widget instance. When the widget is loaded via a script tag with data-assistant-id, the SDK automatically creates a singleton.

const widget = IllumiChat.getInstance();
widget.open();

getInstance() returns null if no widget has been initialized yet.

IllumiChat.destroyInstance()

Destroys the current singleton instance, removes the widget from the DOM, and cleans up all event listeners.

IllumiChat.destroyInstance();

IllumiChat.VERSION

Returns the current SDK version string.

Instance Methods

Method	Returns	Description
`initialize()`	`Promise<void>`	Initialize the widget, create the iframe, and render the launcher
`open()`	`void`	Open the chat panel
`close()`	`void`	Close the chat panel
`toggle()`	`void`	Toggle the chat panel open or closed
`sendMessage(text)`	`void`	Send a message programmatically as if the visitor typed it
`getState()`	`string`	Return the current widget state
`getConfig()`	`object`	Return a copy of the current widget configuration
`destroy()`	`void`	Remove the widget from the DOM and release all resources

initialize()

Must be called before any other method. Creates the iframe, injects styles, and renders the launcher button.

const widget = new IllumiChat.Widget({
  assistantId: 'YOUR_ASSISTANT_ID'
});

try {
  await widget.initialize();
  console.log('Widget is ready');
} catch (error) {
  console.error('Widget failed to initialize:', error);
}

You must call initialize() before calling any other method. Calling open() or sendMessage() on an uninitialized widget has no effect.

open()

Opens the chat panel.

document.getElementById('help-button').addEventListener('click', () => {
  const widget = IllumiChat.getInstance();
  if (widget) widget.open();
});

close()

Closes the chat panel. The launcher button remains visible.

toggle()

Toggles the chat panel. If open it closes; if closed it opens.

sendMessage(text)

Sends a text message as if the visitor typed and submitted it.

widget.open();
widget.sendMessage('I have a question about pricing');

getState()

Returns the current widget state as a string.

destroy()

Removes the widget entirely from the page. After calling destroy(), the instance cannot be reused.

State	Description
`uninitialized`	Instance created but `initialize()` not called
`initializing`	`initialize()` called, setup in progress
`ready`	Initialization complete, launcher visible, panel closed
`open`	Chat panel is visible
`closed`	Chat panel hidden, launcher visible
`error`	An error occurred
`destroyed`	`destroy()` called, widget fully removed

Event System

Subscribing to Events

// Subscribe
const unsubscribe = widget.on('open', () => {
  console.log('Chat panel was opened');
});

// Unsubscribe
unsubscribe();

One-Time Listeners

widget.once('ready', () => {
  console.log('Widget is ready — fires only once');
});

Removing a Specific Handler

function handleOpen() { console.log('Opened'); }
widget.on('open', handleOpen);
widget.off('open', handleOpen);

Available Events

Event	Payload	Description
`ready`	—	Widget finished initializing
`open`	—	Chat panel was opened
`close`	—	Chat panel was closed
`error`	`{ message, code? }`	An error occurred
`message:sent`	`{ content, timestamp }`	The visitor sent a message
`message:received`	`{ content, timestamp }`	The assistant sent a response
`conversation:started`	`{ conversationId }`	A new conversation was initiated
`session:created`	`{ sessionId, visitorId }`	A new session was created
`session:restored`	`{ sessionId, visitorId }`	An existing session was restored
`lead:submitted`	`{ contactId, isNew }`	The lead plugin submitted a contact
`form:submitted`	`{ formId, data }`	The active lead, ticket, or custom form was submitted successfully
`form:error`	`{ error }`	The active form submission failed with a visitor-safe error
`form:hide`	—	The active form was closed
`live_chat:started`	`{ sessionId, agentName, agentId }`	A live-support session was assigned
`live_chat:message`	`{ sessionId, content, senderType, senderName?, senderAvatar? }`	A live-support message was delivered
`live_chat:queue_update`	`{ sessionId, position }`	The visitor’s queue position changed
`live_chat:ended`	`{ sessionId, endedBy }`	The live-support session ended

Event Examples

Track conversations in analytics:

widget.on('conversation:started', ({ conversationId }) => {
  analytics.track('Chat Started', { conversationId });
});

widget.on('message:sent', ({ content }) => {
  analytics.track('Chat Message Sent', { content });
});

Capture leads and forward to a CRM:

widget.on('lead:submitted', ({ contactId, isNew }) => {
  analytics.track('Lead Captured', { contactId, isNew });
});

Handle errors:

widget.on('error', ({ message, code }) => {
  console.error('Widget error:', code, message);
  document.getElementById('fallback-support').style.display = 'block';
});

Observe forms and live support:

widget.on('form:submitted', ({ formId, data }) => {
  analytics.track('Widget Form Submitted', { formId, fieldCount: Object.keys(data).length });
});

widget.on('live_chat:started', ({ sessionId, agentName }) => {
  analytics.track('Live Support Started', { sessionId, agentName });
});

Production capability notes

Text messages, forms, quick-reply actions, and live-support lifecycle events are supported by the production v2 experience.
Attachments and browser voice input are fast-follow composer capabilities. Do not use SDK configuration to infer that those controls are visible.
The plugin registration API remains available for compatibility and host-side lifecycle integrations. Plugin-rendered widget UI is a fast-follow v2 capability and should not be treated as generally available.

Configuration Reference

interface WidgetConfig {
  assistantId: string;
  position?: 'bottom-right' | 'bottom-left';
  authMode?: 'anonymous' | 'authenticated' | 'auto';
  branding?: {
    primaryColor?: string;    // Default: "#6366f1"
    companyName?: string;
    launcherSize?: number;    // Default: 60
  };
  autoOpen?: number;          // Delay in ms, 0 to disable
  suggestedMessages?: string[];
  popupMessages?: string[];   // Teaser bubbles above the launcher
  suggestedMessagesBubbles?: {
    enabled?: boolean;        // Default: false (dashboard toggle overrides)
    delay?: number;           // Default: 3000
  };
  metadata?: Record<string, string | number | boolean>;
  session?: {
    persist?: boolean;        // Default: true
  };
  debug?: boolean;            // Default: false
}

TypeScript Declarations

declare global {
  interface Window {
    IllumiChat: {
      Widget: new (config: WidgetConfig) => WidgetInstance;
      getInstance: () => WidgetInstance | null;
      destroyInstance: () => void;
      VERSION: string;
    };
  }
}

interface WidgetInstance {
  initialize(): Promise<void>;
  open(): void;
  close(): void;
  toggle(): void;
  sendMessage(text: string): void;
  getState(): string;
  getConfig(): object;
  destroy(): void;
  on(event: string, handler: Function): () => void;
  once(event: string, handler: Function): () => void;
  off(event: string, handler: Function): void;
}

Troubleshooting

Problem	Likely Cause	Solution
`IllumiChat is not defined`	SDK script not loaded yet	Wait for the `load` event or check script URL
`getInstance()` returns `null`	No widget initialized	Call `new IllumiChat.Widget(config).initialize()` first
`open()` has no effect	Widget not yet initialized	Await `initialize()` or listen for `ready` event
Widget appears but does not respond	Incorrect assistant ID	Verify the ID in your assistant’s Widget settings
Console shows CORS errors	Domain not authorized	Add your domain to the widget’s allowed domains list
Multiple launcher buttons	Widget initialized twice	Call `destroyInstance()` before creating a new instance

Widget

SDK Reference

Global API

IllumiChat.Widget

IllumiChat.getInstance()

IllumiChat.destroyInstance()

IllumiChat.VERSION

Instance Methods

initialize()

open()

close()

toggle()

sendMessage(text)

getState()

destroy()

Widget States

Event System

Subscribing to Events

One-Time Listeners

Removing a Specific Handler

Available Events

Event Examples

Production capability notes

Configuration Reference

TypeScript Declarations

Troubleshooting

​Global API

​IllumiChat.Widget

​IllumiChat.getInstance()

​IllumiChat.destroyInstance()

​IllumiChat.VERSION

​Instance Methods

​initialize()

​open()

​close()

​toggle()

​sendMessage(text)

​getState()

​destroy()

​Widget States

​Event System

​Subscribing to Events

​One-Time Listeners

​Removing a Specific Handler

​Available Events

​Event Examples

​Production capability notes

​Configuration Reference

​TypeScript Declarations

​Troubleshooting

Global API

IllumiChat.Widget

IllumiChat.getInstance()

IllumiChat.destroyInstance()

IllumiChat.VERSION

Instance Methods

initialize()

open()

close()

toggle()

sendMessage(text)

getState()

destroy()

Widget States

Event System

Subscribing to Events

One-Time Listeners

Removing a Specific Handler

Available Events

Event Examples

Production capability notes

Configuration Reference

TypeScript Declarations

Troubleshooting