Configure the widget through HTML data attributes on the script tag or through the JavaScript API.
Script Tag Attributes
| Attribute | Required | Default | Description |
|---|
data-assistant-id | Yes | — | Your assistant’s unique ID |
data-position | No | bottom-right | Widget position: bottom-right, bottom-left, top-right, top-left |
data-theme | No | auto | Color theme: light, dark, auto |
data-primary-color | No | #0D9373 | Primary brand color as a hex value |
data-auth-mode | No | anonymous | Auth mode: anonymous, authenticated, auto |
data-debug | No | false | Enable debug logging to browser console |
Full Example
<script
src="https://widget.illumichat.com/v1/widget.js"
data-assistant-id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
data-position="bottom-left"
data-theme="light"
data-primary-color="#6366f1"
data-auth-mode="anonymous"
async
></script>
Script tag attributes are the fastest way to get started. For dynamic configuration — such as changing colors based on the page or passing user metadata — use the programmatic API instead.
Programmatic Configuration
For full control, create a widget instance with the JavaScript API:
const widget = new IllumiChat.Widget({
assistantId: 'YOUR_ASSISTANT_ID',
position: 'bottom-right',
branding: {
primaryColor: '#6366f1',
companyName: 'Acme Corp',
launcherSize: 60
},
autoOpen: 3000,
suggestedMessages: [
'How can you help me?',
'Tell me about pricing',
'I need technical support'
],
metadata: {
page: window.location.pathname,
userId: '12345'
},
session: { persist: true },
authMode: 'anonymous'
});
await widget.initialize();
When using the programmatic API, do not include data-assistant-id on the script tag. The script’s auto-initialization runs only when that attribute is present.
Authentication Modes
Anonymous
{ authMode: 'anonymous' }
Authenticated
{ authMode: 'authenticated' }
Auto
A hybrid mode. If the visitor is already logged in through Auth0 on your site, the widget uses their authenticated identity. Otherwise, it falls back to anonymous mode.
Appearance
Brand Color
The primary color controls the chat bubble, header, send button, and accent elements.
<script
src="https://widget.illumichat.com/v1/widget.js"
data-assistant-id="YOUR_ASSISTANT_ID"
data-primary-color="#6366f1"
async
></script>
Position
| Value | Description |
|---|
bottom-right | Bottom-right corner (default) |
bottom-left | Bottom-left corner |
top-right | Top-right corner |
top-left | Top-left corner |
Theme
| Value | Description |
|---|
light | Light background with dark text |
dark | Dark background with light text |
auto | Matches the visitor’s system preference (default) |
Behavior
Suggested Messages
Display clickable chips when the chat panel opens to guide visitors:
suggestedMessages: [
'How can you help me?',
'Tell me about pricing',
'I need technical support'
]
Auto-Open
Automatically open the chat panel after a delay (in milliseconds):
autoOpen: 5000 // Open after 5 seconds
Use auto-open sparingly. A delay of 3 to 10 seconds works well for most use cases.
Session Persistence
Sessions persist across page loads by default, so visitors do not lose their conversation when navigating your site:
session: { persist: true } // Default: true
metadata: {
page: window.location.pathname,
userId: 'user_12345',
plan: 'enterprise'
}
Lead Capture
Lead capture collects visitor information (name, email, phone) before or during a conversation. Configure it in your assistant’s settings:
- Open your assistant’s Settings page
- Navigate to the Widget tab
- Toggle Lead Capture on
- Choose which fields to collect
- Save your changes
Listen for lead submissions:
const widget = IllumiChat.getInstance();
widget.on('lead:submitted', (data) => {
console.log('Lead captured:', data);
});
Next Steps
