The IllumiChat Widget SDK provides a JavaScript API for creating, controlling, and responding to widget events programmatically.
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 | { error } | An error occurred |
message:sent | { text } | The visitor sent a message |
message:received | { text } | The assistant sent a response |
conversation:started | { sessionId } | A new conversation was initiated |
session:created | { sessionId } | A new session was created |
session:restored | { sessionId } | An existing session was restored |
lead:submitted | { data } | The visitor submitted the lead form |
Event Examples
Track conversations in analytics:
widget.on('conversation:started', ({ sessionId }) => {
analytics.track('Chat Started', { sessionId });
});
widget.on('message:sent', ({ text }) => {
analytics.track('Chat Message Sent', { text });
});
widget.on('lead:submitted', ({ data }) => {
fetch('/api/leads', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
});
});
widget.on('error', ({ error }) => {
console.error('Widget error:', error);
document.getElementById('fallback-support').style.display = 'block';
});
Configuration Reference
interface WidgetConfig {
assistantId: string;
position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
theme?: 'light' | 'dark' | 'auto';
authMode?: 'anonymous' | 'authenticated' | 'auto';
branding?: {
primaryColor?: string; // Default: "#0D9373"
companyName?: string;
launcherSize?: number; // Default: 60
};
autoOpen?: number; // Delay in ms, 0 to disable
suggestedMessages?: string[];
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 |
