Skip to main content
Configure the widget through HTML data attributes on the script tag or through the JavaScript API.

​
Script Tag Attributes

AttributeRequiredDefaultDescription
data-assistant-idYes—Your assistant’s unique ID
data-positionNobottom-rightWidget position: bottom-right or bottom-left
data-primary-colorNo#6366f1Primary brand color as a hex value
data-auth-modeNoanonymousAuth mode: anonymous, authenticated, auto
data-debugNofalseEnable 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-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' }
The default mode. Visitors are tracked by an automatically generated visitor ID stored in the browser. No login required. Best for public-facing websites.

​
Authenticated

{ authMode: 'authenticated' }
Requires visitors to log in through Auth0 before chatting. Use this for internal tools or customer portals where you need verified identities.

​
Auto

{ authMode: '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

ValueDescription
bottom-rightBottom-right corner (default)
bottom-leftBottom-left corner

​
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

Attach custom key-value pairs to every conversation for filtering and analytics: 
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:
  1. Open your assistant’s Settings page
  2. Navigate to the Widget tab
  3. Toggle Lead Capture on
  4. Choose which fields to collect
  5. Save your changes
Listen for lead submissions: 
const widget = IllumiChat.getInstance();
widget.on('lead:submitted', (data) => {
  console.log('Lead captured:', data);
});

​
Next Steps

SDK Reference

Full JavaScript API documentation for programmatic widget control.

Installation

Framework-specific installation guides.