IllumiChat - AI-Powered Chat Platform

Configure the widget through HTML data attributes on the script tag or through the JavaScript API.

The production widget is AI-first. Embed and SDK configuration customize the experience; they do not select a widget version or change how a conversation starts. Live-support handoff remains available from the AI conversation.

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` or `bottom-left`
`data-primary-color`	No	`#6366f1`	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-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>

const widget = new IllumiChat.Widget({
  assistantId: 'YOUR_ASSISTANT_ID',
  branding: { primaryColor: '#6366f1' }
});

Position

Value	Description
`bottom-right`	Bottom-right corner (default)
`bottom-left`	Bottom-left corner

Behavior

The production composer supports text messages, quick replies, forms, and live support handoff. Attachments, browser voice input, and plugin-rendered widget UI are fast-follow capabilities. Legacy or SDK configuration fields for those features do not make their controls available in the production v2 composer.

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'
]

Show floating teaser bubbles above the launcher button to draw visitors in — distinct from Suggested Messages, which appear inside the chat panel. Clicking a bubble opens the chat; visitors can dismiss bubbles, and dismissals are remembered per visitor. The easiest way to configure popup messages is in the dashboard under Widget → Styles → Popup messages — set up to 3 messages and a delay, and they apply everywhere the widget is installed without touching your embed code. You can also configure them programmatically:

popupMessages: [
  'Hi there! Have any questions?',
  'We reply in minutes.'
],
suggestedMessagesBubbles: {
  enabled: true,
  delay: 3000  // Milliseconds before the bubbles appear
}

Configuration passed in code takes priority over dashboard settings on that page. If popupMessages is not set, the bubbles fall back to showing your suggestedMessages list.

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:

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

Rollout

Rollout controls where and for whom the launcher appears, so you can test on a real page before going live for everyone. Set it on your assistant’s Embed page, under Rollout. There are three modes:

Everyone (default)

The widget is live for all visitors on every page where the embed code is installed.

Specific pages

The launcher only appears on URL paths you list — one glob per line, each starting with /. Use * to match anything:

/pricing
/products/*
/help

/products/* matches /products/shoes and /products/shoes/blue. This is a client-side rule — it decides whether the launcher mounts based on the page URL.

Test link only

The widget is hidden from everyone except people who open your secret test link. The Embed page generates a URL like https://your-site.com/any-page?ic_test=<token> — open any installed page with that ?ic_test=… and the widget appears for that browser tab (it’s remembered as you navigate the site). Everyone else sees nothing.This is enforced on the server too: without the correct token, a chat session can’t be created. Use Regenerate to rotate the token — the previous link stops working immediately.

Rollout controls launcher visibility. It does not select a v1/v2 renderer, change the AI-first conversation behavior, or throttle traffic by percentage. The secret test token is never exposed in the widget’s public configuration.

Widget

Configuration

Script Tag Attributes

Full Example

Programmatic Configuration

Authentication Modes

Anonymous

Authenticated

Auto

Appearance

Brand Color

Position

Behavior

Suggested Messages

Auto-Open

Session Persistence

Metadata

Lead Capture

Rollout

Next Steps

SDK Reference

Installation

​Script Tag Attributes

​Full Example

​Programmatic Configuration

​Authentication Modes

​Anonymous

​Authenticated

​Auto

​Appearance

​Brand Color

​Position

​Behavior

​Suggested Messages

​Popup Messages

​Auto-Open

​Session Persistence

​Metadata

​Lead Capture

​Rollout

​Next Steps

SDK Reference

Installation

Script Tag Attributes

Full Example

Programmatic Configuration

Authentication Modes

Anonymous

Authenticated

Auto

Appearance

Brand Color

Position

Behavior

Suggested Messages

Popup Messages

Auto-Open

Session Persistence

Metadata

Lead Capture

Rollout

Next Steps