> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Customize widget appearance and behavior

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

<Note>
  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.
</Note>

## 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

```html theme={null}
<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>
```

<Tip>
  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.
</Tip>

## Programmatic Configuration

For full control, create a widget instance with the JavaScript API:

```javascript theme={null}
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();
```

<Note>
  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.
</Note>

## Authentication Modes

### Anonymous

```javascript theme={null}
{ 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

```javascript theme={null}
{ 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

```javascript theme={null}
{ 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.

<CodeGroup>
  ```html Script Tag theme={null}
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="YOUR_ASSISTANT_ID"
    data-primary-color="#6366f1"
    async
  ></script>
  ```

  ```javascript Programmatic theme={null}
  const widget = new IllumiChat.Widget({
    assistantId: 'YOUR_ASSISTANT_ID',
    branding: { primaryColor: '#6366f1' }
  });
  ```
</CodeGroup>

### 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:

```javascript theme={null}
suggestedMessages: [
  'How can you help me?',
  'Tell me about pricing',
  'I need technical support'
]
```

### Popup Messages

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:

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

<Note>
  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.
</Note>

### Auto-Open

Automatically open the chat panel after a delay (in milliseconds):

```javascript theme={null}
autoOpen: 5000  // Open after 5 seconds
```

<Tip>
  Use auto-open sparingly. A delay of 3 to 10 seconds works well for most use cases.
</Tip>

### Session Persistence

Sessions persist across page loads by default, so visitors do not lose their conversation when navigating your site:

```javascript theme={null}
session: { persist: true }  // Default: true
```

### Metadata

Attach custom key-value pairs to every conversation for filtering and analytics:

```javascript theme={null}
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:

```javascript theme={null}
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:

<AccordionGroup>
  <Accordion title="Everyone (default)">
    The widget is live for all visitors on every page where the embed code is installed.
  </Accordion>

  <Accordion title="Specific pages">
    The launcher only appears on URL paths you list — one glob per line, each starting with `/`. Use `*` to match anything:

    ```text theme={null}
    /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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Note>
  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.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="brackets-curly" href="/widget/sdk-reference">
    Full JavaScript API documentation for programmatic widget control.
  </Card>

  <Card title="Installation" icon="code" href="/widget/installation">
    Framework-specific installation guides.
  </Card>
</CardGroup>