# Account & Billing
Source: https://docs.illumichat.com/account

Manage your Illumichat account and subscription

## Account Settings

Access your account settings by clicking your profile icon in the top-right corner.

### Profile

Update your personal information:

* **Name**: How your name appears in Illumichat
* **Email**: Your login email (contact support to change)
* **Avatar**: Upload a profile picture

### Password

Change your password:

1. Go to **Account Settings → Security**
2. Click **Change Password**
3. Enter your current password and new password
4. Click **Update**

<Note>
  If you signed up with Google, you don't have an Illumichat password.
</Note>

### Preferences

Customize your experience:

* **Theme**: Light, dark, or system
* **Keyboard shortcuts**: Enable/disable shortcuts

## Subscription Plans

### How credits work

Every AI chat message your workspace generates uses **1 credit**. Credits are shared across the whole workspace, **reset monthly**, and do **not** roll over. When a workspace runs out of credits, AI replies stop with a `credits_limit_exceeded` error until the monthly reset or an upgrade — your conversations and data are untouched. You'll see in-app alerts as you approach the limit (\~80%) and when you hit it (100%).

### Plan comparison

|                                                                          | Free      | Pro              | Enterprise      |
| ------------------------------------------------------------------------ | --------- | ---------------- | --------------- |
| **Price**                                                                | \$0       | **\$29 / month** | Custom          |
| **Monthly credits**                                                      | 50        | 1,200            | Custom          |
| **Free trial**                                                           | —         | 14 days          | —               |
| **Workspaces you can create**                                            | 1         | 1                | Unlimited       |
| **CRM contacts**                                                         | 100       | 5,000            | Unlimited       |
| **Support tickets**                                                      | 50        | 1,000            | Unlimited       |
| **Universal Live Inbox**                                                 | ✓         | ✓                | ✓               |
| **Channels** (SMS, Messenger, Instagram, WhatsApp, Shopify, WooCommerce) | —         | ✓                | ✓               |
| **v1 REST API** (Zapier / Make write actions)                            | —         | ✓                | ✓               |
| **SSO / SAML**                                                           | —         | —                | ✓               |
| **Support**                                                              | Community | Priority         | Dedicated + SLA |

### Free

Best for trying IllumiChat — 50 credits/month, one workspace, assistants, a knowledge base, and the [Universal Inbox](/features/inbox) (for your website widget's AI conversations and live-chat handoffs). The messaging **channels** (Messenger, Instagram, WhatsApp, Shopify, WooCommerce) are not included on Free.

### Pro — \$29/month

Everything you need to run AI support across channels: 1,200 credits/month, all channel integrations (SMS, Messenger, Instagram, WhatsApp, Shopify, WooCommerce) feeding into the [Universal Inbox](/features/inbox), the v1 REST API for Zapier/Make, and priority support. (The inbox itself is on every plan — Pro adds the channels that populate it, plus far more credits.) New workspaces start on a **14-day Pro trial** automatically.

### Enterprise

Custom plans for larger teams: custom credit limits, SSO/SAML, dedicated support, and SLA guarantees.

<Card title="Contact Sales" icon="building" href="mailto:sales@illumichat.com">
  Get a custom quote for your organization
</Card>

### Trial & plan changes

* **New workspaces get a 14-day Pro trial** automatically — no card required; the countdown starts at signup.
* When the trial ends, the workspace **auto-downgrades to Free** (credits drop to the Free allowance and channel/inbox features turn off) unless you've upgraded.
* Upgrades take effect immediately; downgrades take effect at the end of the current billing period. Credits never roll over between months.

## Managing Your Subscription

### Upgrading

1. Go to **Account Settings → Billing**
2. Click **Upgrade**
3. Select your plan
4. Enter payment information
5. Confirm

Your new plan takes effect immediately.

### Downgrading

1. Go to **Account Settings → Billing**
2. Click **Change Plan**
3. Select the lower plan
4. Confirm

Changes take effect at the end of your current billing period.

### Canceling

1. Go to **Account Settings → Billing**
2. Click **Cancel Subscription**
3. Confirm cancellation

You'll retain access until the end of your billing period.

<Warning>
  Canceling deletes your data after 30 days. Export anything you need before canceling.
</Warning>

## Billing

### Payment Methods

We accept:

* Credit and debit cards (Visa, Mastercard, Amex)
* Link
* Apple Pay / Google Pay

### Invoices

Access invoices from **Account Settings → Billing → Invoices**.

All invoices are emailed automatically and available for download.

### Updating Payment Method

1. Go to **Account Settings → Billing**
2. Click **Payment Method**
3. Add or update your card
4. Click **Save**

## Data & Privacy

### Exporting Your Data

Download all your data:

1. Go to **Account Settings → Privacy**
2. Click **Export Data**
3. You'll receive an email with a download link

Export includes:

* All conversations
* Account settings

### Deleting Your Account

Permanently delete your account and all data:

1. Go to **Account Settings → Privacy**
2. Click **Delete Account**
3. Type "DELETE" to confirm
4. Click **Permanently Delete**

<Warning>
  This action is irreversible. All your data will be permanently deleted.
</Warning>

## Getting Help

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:support@illumichat.com">
    [support@illumichat.com](mailto:support@illumichat.com)
  </Card>

  <Card title="Help Center" icon="circle-question" href="/help">
    Browse common questions
  </Card>
</CardGroup>


# Assistants
Source: https://docs.illumichat.com/api/assistants

Create and configure AI assistants with custom instructions, knowledge base connections, and SMS capabilities.

Assistants are the core conversational entities in IllumiChat. Each assistant has its own system prompt and its own knowledge base for retrieval-augmented generation (RAG). All assistants use the same AI model.

<Warning>
  **These endpoints require a signed-in browser session, not an API key.** There is currently no API-key accessible Assistants API — a workspace API key (`Authorization: Bearer ...`) is only accepted on the `/api/v1/*` endpoints (contacts, messages, tickets). See [API Overview](/api/overview) for the two surfaces.
</Warning>

## Assistant Configuration

| Field            | Type    | Default       | Description                                                                                                                 |
| ---------------- | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string  | --            | Display name shown to users.                                                                                                |
| `instructions`   | string  | `""`          | System prompt that defines the assistant's behavior and persona.                                                            |
| `visibility`     | string  | `"workspace"` | Access level: `private` or `workspace`. (`public` is accepted for backward compatibility but is legacy -- use `workspace`.) |
| `temperature`    | number  | `0.7`         | Sampling temperature between `0` and `2`. Lower values produce more focused responses.                                      |
| `maxTokens`      | integer | `4096`        | Maximum number of tokens in the assistant's response.                                                                       |
| `welcomeMessage` | string  | `null`        | Initial message displayed when a conversation starts.                                                                       |

### Visibility Levels

`visibility` governs access to the assistant in the internal Chat workspace only -- it has no effect on the embeddable widget. Widget access is controlled by the widget's own `isEnabled` flag (part of the assistant's **widget configuration**, not the assistant object -- see the Widget endpoints), independent of `visibility`.

| Visibility          | Who Can Access                                                                                                    |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `workspace`         | Active members of the workspace.                                                                                  |
| `private`           | Only the creator, workspace admins, and users with explicit access grants.                                        |
| `public` *(legacy)* | Accepted for backward compatibility (legacy link-share access). Do not use for new assistants -- use `workspace`. |

***

## List Assistants

Returns assistants accessible to the authenticated user within a workspace. `workspaceId` is required.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/assistants?workspaceId=ws_abc123&limit=10" \
  -H "Cookie: <your-session-cookie>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "ast_abc123",
      "name": "Support Bot",
      "model": "auto",
      "visibility": "workspace",
      "createdAt": "2025-07-01T09:00:00Z"
    }
  ],
  "total": 5,
  "limit": 10,
  "offset": 0
}
```

***

## Create Assistant

Creates a new assistant in the workspace. Requires `owner` or `admin` role.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/assistants" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "instructions": "You are a helpful customer support assistant for Acme Corp.",
    "visibility": "workspace",
    "temperature": 0.5,
    "maxTokens": 2048,
    "welcomeMessage": "Hello! How can I help you today?"
  }'
```

**Response** `201 Created` with the full assistant object.

***

## Get Assistant

Retrieves a single assistant by ID.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>"
```

**Response** `200 OK` with the full assistant object including `instructions`, `temperature`, `maxTokens`, `visibility`, `welcomeMessage`, and timestamps.

***

## Update Assistant

Updates an assistant's configuration. Requires `owner` or `admin` role. All fields are optional; only provided fields are updated.

```bash theme={null}
curl -X PATCH "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a technical support specialist. Always ask clarifying questions.",
    "temperature": 0.3
  }'
```

**Response** `200 OK` with the updated assistant object.

***

## Delete Assistant

Permanently deletes an assistant and all its conversations. Requires `owner` or `admin` role.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>"
```

**Response** `204 No Content`

<Warning>
  Deleting an assistant permanently removes all associated conversations, widget sessions, and SMS configurations. This action cannot be undone.
</Warning>

***

## Knowledge (RAG)

Each assistant owns its own knowledge base, and it is managed in the app rather than over the public API — there is no endpoint for connecting a separate document collection. When a customer sends a message, the assistant searches its own static sources for relevant context and includes it in the prompt.

<Note>
  Static sources (files, websites, text, Q\&A) are chunked, embedded, and stored in a vector database (Pinecone) under a namespace dedicated to that assistant's knowledge base. Realtime sources (Shopify, WooCommerce, spreadsheets) are read live at question time and are never indexed. See [Knowledge Base](/features/knowledge-base).
</Note>

***

## SMS Configuration

Assistants can be configured to send and receive SMS messages via Twilio. Each assistant has its own Twilio credentials using a bring-your-own-key (BYOK) model.

### Get SMS Config

Requires `admin` role or above.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": {
    "isEnabled": true,
    "twilioPhoneNumber": "+15551234567",
    "twilioAccountSid": "AC...",
    "webhookUrl": "https://app.illumichat.com/api/sms/webhook/ast_abc123",
    "maxMessageLength": 1600,
    "createdAt": "2025-08-15T10:00:00Z"
  }
}
```

### Create or Update SMS Config

Use `POST` to create the configuration and `PATCH` to update an existing one. On `PATCH` every field is optional; only the fields you send are changed.

```bash theme={null}
curl -X PATCH "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": true,
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "twilioPhoneNumber": "+15551234567",
    "maxMessageLength": 1600
  }'
```

| Parameter               | Type    | Required on `POST` | Description                                                              |
| ----------------------- | ------- | ------------------ | ------------------------------------------------------------------------ |
| `twilioAccountSid`      | string  | Yes                | Your Twilio Account SID. Must start with `AC` followed by 32 characters. |
| `twilioAuthToken`       | string  | Yes                | Your Twilio Auth Token (min 32 characters). Stored encrypted.            |
| `twilioPhoneNumber`     | string  | Yes                | Twilio phone number in E.164 format, e.g. `+15551234567`.                |
| `isEnabled`             | boolean | No                 | Whether SMS is active for this assistant. Default `true`.                |
| `maxMessageLength`      | integer | No                 | Characters per outbound message, `50`--`1600`. Default `1600`.           |
| `enableContactMatching` | boolean | No                 | Match inbound senders to existing CRM contacts. Default `true`.          |
| `autoCreateContacts`    | boolean | No                 | Create a contact for an unrecognized sender. Default `true`.             |

### Delete SMS Config

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>"
```

**Response** `204 No Content`

### Test SMS Credentials

Validates the provided Twilio credentials without saving them.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/assistants/ast_abc123/sms/test" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "twilioPhoneNumber": "+15551234567"
  }'
```

**Response** `200 OK`

```json theme={null}
{
  "data": {
    "valid": true,
    "phoneNumberCapabilities": { "sms": true, "mms": true, "voice": true }
  }
}
```

### List SMS Sessions

Returns the assistant's SMS conversations, most recent first.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123/sms/sessions?limit=10&offset=0" \
  -H "Cookie: <your-session-cookie>"
```

<Note>
  There is no per-assistant SMS analytics endpoint. For message volume broken down by channel, use `GET /api/analytics/channels`.
</Note>

<Tip>
  After configuring SMS, set the Twilio webhook URL to the value returned in the `webhookUrl` field of the SMS config response. This URL handles inbound messages from your customers.
</Tip>


# Authentication
Source: https://docs.illumichat.com/api/authentication

How to authenticate API requests

IllumiChat supports two authentication methods. **Session authentication** (Auth0) is used by the app and browser-based requests. **Workspace API keys** are used for server-to-server access and no-code integrations such as Zapier.

## Session Authentication

Session-based authentication is the primary method for browser-based applications. When a user logs in at `app.illumichat.com`, Auth0 issues a session cookie that is automatically included in subsequent requests.

| Detail      | Value                  |
| ----------- | ---------------------- |
| Cookie name | `authjs.session-token` |
| Set by      | Auth0 login flow       |
| Scope       | `app.illumichat.com`   |

For browser-based integrations, include `credentials: "include"` in your fetch calls:

```javascript theme={null}
const response = await fetch("https://app.illumichat.com/api/assistants", {
  method: "GET",
  credentials: "include",
});
```

## API Key Authentication

Workspace API keys authenticate server-to-server requests to the public v1 REST API and power the [Zapier integration](/features/zapier). A key acts on behalf of the whole workspace, not an individual user.

<Note>
  API keys use a static bearer token — there is **no OAuth2 flow**. Auth0 sessions remain the mechanism for browser and in-app requests.
</Note>

### Creating a key

Go to **Settings → API Keys** in IllumiChat and create a key. Keys begin with the prefix `wsk_live_`. The full key is shown **only once** at creation time — copy it somewhere safe. Only workspace **owners** and **admins** can create or revoke keys.

<Warning>
  Creating and using API keys for write actions requires a **Pro plan or higher**. Requests from Free workspaces are rejected with `403 plan_upgrade_required`.
</Warning>

### Making authenticated requests

Send the key as a bearer token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://app.illumichat.com/api/v1/contacts \
    -H "Authorization: Bearer wsk_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://app.illumichat.com/api/v1/contacts", {
    headers: {
      Authorization: "Bearer wsk_live_xxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
  });
  ```
</CodeGroup>

### Scopes

Each key carries one or more scopes. A request that needs a scope the key lacks is rejected with `403 missing_scope`. Grant only the scopes an integration needs.

| Scope            | Grants                                                     |
| ---------------- | ---------------------------------------------------------- |
| `contacts:write` | Create and update CRM contacts                             |
| `tickets:write`  | Create and update support tickets                          |
| `chat:write`     | Send messages into live chat sessions                      |
| `events:read`    | Subscribe to workspace events (webhooks / Zapier triggers) |

### Revoking a key

Revoke a key from **Settings → API Keys** at any time. Revocation is immediate and disconnects every integration — including any Zaps — using that key.

## Public Endpoints

The following endpoints do not require authentication:

### Widget Endpoints

| Method | Endpoint                             | Description                            |
| ------ | ------------------------------------ | -------------------------------------- |
| `GET`  | `/api/widget/{assistantId}/config`   | Retrieve widget configuration          |
| `POST` | `/api/widget/{assistantId}/session`  | Create a widget chat session           |
| `POST` | `/api/widget/{assistantId}/chat`     | Send a message via the widget          |
| `POST` | `/api/widget/{assistantId}/lead`     | Capture a lead from the widget         |
| `POST` | `/api/widget/{assistantId}/feedback` | Submit conversation feedback           |
| `GET`  | `/api/widget/{assistantId}/history`  | Retrieve widget chat history           |
| `POST` | `/api/widget/tickets/create`         | Create a support ticket (rate limited) |

### SMS Webhooks

| Method | Endpoint                         | Description                     |
| ------ | -------------------------------- | ------------------------------- |
| `POST` | `/api/sms/webhook/{assistantId}` | Inbound SMS from Twilio         |
| `POST` | `/api/sms/status/{assistantId}`  | Twilio delivery status callback |

<Note>
  SMS webhook endpoints validate the **Twilio request signature** to verify that incoming requests originate from Twilio.
</Note>

## Authorization

After authentication, IllumiChat checks your permissions before processing each request.

### Workspace Roles

| Role     | Capabilities                                       |
| -------- | -------------------------------------------------- |
| `owner`  | Full control including billing, workspace deletion |
| `admin`  | Manage members, assistants, settings               |
| `member` | Use assistants, create and view chats              |
| `guest`  | Limited read-only access                           |

### Assistant Visibility

`visibility` governs access to the assistant in the internal Chat workspace, not the embeddable widget (which is controlled by the widget configuration's own `isEnabled` flag).

| Visibility  | Who Can Access                                |
| ----------- | --------------------------------------------- |
| `workspace` | Active workspace members                      |
| `private`   | Creator, admins, and explicitly granted users |

## Auth Error Responses

| Status | Meaning                                             | What to Do                      |
| ------ | --------------------------------------------------- | ------------------------------- |
| `401`  | **Unauthorized** -- missing or expired session      | Redirect the user to login      |
| `403`  | **Forbidden** -- authenticated but lacks permission | Check the user's workspace role |

<Warning>
  Session tokens expire based on Auth0 configuration. If you receive a `401` response, prompt the user to re-authenticate rather than retrying.
</Warning>


# Errors & Status Codes
Source: https://docs.illumichat.com/api/errors

Standard error format and error code reference

When an API request fails, IllumiChat returns a structured error response with an HTTP status code, a human-readable message, and a machine-readable error code.

## Error Response Format

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "error_type:context"
}
```

| Field   | Type     | Description                                                          |
| ------- | -------- | -------------------------------------------------------------------- |
| `error` | `string` | A message suitable for displaying to users or logging                |
| `code`  | `string` | A structured code in `type:context` format for programmatic handling |

### Validation Errors

Some endpoints return field-level details when validation fails:

```json theme={null}
{
  "error": "Validation failed",
  "code": "bad_request:api",
  "details": {
    "name": "Name is required",
    "email": "Invalid email format"
  }
}
```

## HTTP Status Codes

| Code  | Meaning                   | Description                                        |
| ----- | ------------------------- | -------------------------------------------------- |
| `200` | **OK**                    | Successful `GET`, `PATCH`, or `DELETE` request     |
| `201` | **Created**               | Successful `POST` request that created a resource  |
| `400` | **Bad Request**           | Validation failed or required fields are missing   |
| `401` | **Unauthorized**          | Not authenticated -- session is missing or expired |
| `403` | **Forbidden**             | Authenticated but insufficient permissions         |
| `404` | **Not Found**             | The requested resource does not exist              |
| `409` | **Conflict**              | Resource already exists (e.g., duplicate name)     |
| `429` | **Too Many Requests**     | Rate limit exceeded                                |
| `500` | **Internal Server Error** | An unexpected error occurred on the server         |

## Error Code Reference

### Authentication & Authorization

| Code                  | HTTP Status | Description                                |
| --------------------- | ----------- | ------------------------------------------ |
| `unauthorized:api`    | `401`       | Not authenticated for an API operation     |
| `unauthorized:chat`   | `401`       | Not authenticated for a chat operation     |
| `unauthorized:widget` | `401`       | Not authenticated for a widget operation   |
| `forbidden:api`       | `403`       | Insufficient permissions for the operation |

### Request Errors

| Code               | HTTP Status | Description                                  |
| ------------------ | ----------- | -------------------------------------------- |
| `bad_request:api`  | `400`       | Invalid request parameters or missing fields |
| `bad_request:chat` | `400`       | Invalid chat request                         |
| `not_found:api`    | `404`       | Requested resource was not found             |
| `not_found:chat`   | `404`       | Chat conversation not found                  |
| `not_found:widget` | `404`       | Widget configuration not found               |
| `conflict:api`     | `409`       | Resource conflict such as a duplicate entry  |

### Billing & Quota Errors

| Code                     | HTTP Status | Description                                                                                                                                                                     |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credits_limit_exceeded` | `403`       | The workspace has used all of its monthly credits. Chat is blocked until credits reset (monthly) or the workspace upgrades. See [Plans & credits](/account#subscription-plans). |

### Rate Limit Errors

| Code                | HTTP Status | Description                         |
| ------------------- | ----------- | ----------------------------------- |
| `rate_limit:widget` | `429`       | Widget endpoint rate limit exceeded |

### Server Errors

| Code                        | HTTP Status | Description                  |
| --------------------------- | ----------- | ---------------------------- |
| `internal_server_error:api` | `500`       | Unexpected server-side error |

## Handling Errors

### Check the HTTP status code first

```javascript theme={null}
const response = await fetch("https://app.illumichat.com/api/assistants", {
  credentials: "include",
});

if (!response.ok) {
  const { error, code } = await response.json();

  switch (response.status) {
    case 401:
      window.location.href = "/login";
      break;
    case 403:
      showError("You don't have access to this resource.");
      break;
    case 429:
      await delay(getBackoffMs(retryCount));
      break;
    default:
      console.error(`API error [${code}]: ${error}`);
      showError(error);
  }
}
```

### Use the `code` field for programmatic handling

The `code` field is a stable identifier you can match against, while the `error` message may change.

```javascript theme={null}
if (code === "not_found:assistant") {
  router.push("/assistants");
} else if (code === "forbidden:api") {
  showUpgradePrompt();
}
```

### Handle 429s with exponential backoff

```javascript theme={null}
function getBackoffMs(retryCount) {
  return Math.min(1000 * Math.pow(2, retryCount), 30000);
}
```

<Tip>
  Log the full error response (including `code` and `details`) to make debugging easier during development.
</Tip>


# API Overview
Source: https://docs.illumichat.com/api/overview

Introduction to the IllumiChat API

The IllumiChat API lets you manage assistants, conversations, contacts, tickets, and more. All endpoints follow REST conventions and return JSON responses.

## Base URL

```
https://app.illumichat.com/api
```

## Request Format

* Use `Content-Type: application/json` for request bodies
* Include authentication credentials with every request (see [Authentication](/api/authentication))
* URL path parameters are denoted with `{paramName}` in the endpoint documentation

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://app.illumichat.com/api/assistants \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://app.illumichat.com/api/assistants", {
    headers: {
      Authorization: "Bearer <your-token>",
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.illumichat.com/api/assistants",
      headers={
          "Authorization": "Bearer <your-token>",
          "Content-Type": "application/json",
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response Format

All successful responses return JSON. The structure depends on the endpoint:

```json theme={null}
// Single resource
{
  "id": "abc123",
  "name": "My Assistant",
  "createdAt": "2025-01-15T10:30:00Z"
}

// Collection
[
  { "id": "abc123", "name": "Assistant A" },
  { "id": "def456", "name": "Assistant B" }
]
```

Error responses use a consistent format described in [Errors & Status Codes](/api/errors).

## Authentication Methods

| Method               | Use Case              | Details                             |
| -------------------- | --------------------- | ----------------------------------- |
| **Session cookie**   | Browser-based apps    | Set automatically after Auth0 login |
| **Bearer token**     | Server-to-server      | Pass in `Authorization` header      |
| **Public (no auth)** | Widget & SMS webhooks | Rate-limited by IP or assistant     |

See [Authentication](/api/authentication) for full details.

## API Sections

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Session cookies, API keys, and public endpoints.
  </Card>

  <Card title="Errors & Status Codes" icon="circle-exclamation" href="/api/errors">
    Error format, HTTP codes, and handling patterns.
  </Card>

  <Card title="Rate Limiting" icon="gauge-high" href="/api/rate-limiting">
    Request limits, widget quotas, and backoff strategies.
  </Card>

  <Card title="Endpoint Reference" icon="code" href="/api/authentication">
    Browse individual endpoint documentation generated from the OpenAPI spec.
  </Card>
</CardGroup>

## Key Endpoint Groups

Two surfaces exist and they authenticate differently — check which one an endpoint belongs to before writing an integration:

**API-key surface (`/api/v1/*`)** — the endpoints an external integration can call with `Authorization: Bearer <your-api-key>`. Write access additionally requires the `api_v1_write` plan feature.

| Group        | Base Path          | Description                |
| ------------ | ------------------ | -------------------------- |
| **Contacts** | `/api/v1/contacts` | Create and manage contacts |
| **Messages** | `/api/v1/messages` | Send messages              |
| **Tickets**  | `/api/v1/tickets`  | Support ticket lifecycle   |

**Session surface** — these require a signed-in browser session, **not** an API key. They power the IllumiChat app itself; an API key will be rejected.

| Group          | Base Path                  | Description                                   |
| -------------- | -------------------------- | --------------------------------------------- |
| **Assistants** | `/api/assistants`          | Create, update, and manage AI assistants      |
| **Inbox**      | `/api/inbox/conversations` | Read conversations and reply as a human agent |
| **Webhooks**   | `/api/webhooks`            | Manage webhook subscriptions                  |

**Public / unauthenticated** — no credentials, scoped to one assistant or used by providers.

| Group      | Base Path                        | Description                    |
| ---------- | -------------------------------- | ------------------------------ |
| **Widget** | `/api/widget/{assistantId}`      | Public widget endpoints        |
| **SMS**    | `/api/sms/webhook/{assistantId}` | Twilio inbound/status webhooks |

<Tip>
  The full OpenAPI specification is available and powers the auto-generated endpoint pages in this documentation. You can also download it for use with tools like Postman or code generators.
</Tip>


# Pagination
Source: https://docs.illumichat.com/api/pagination

Learn how to paginate through API results using offset-based and cursor-based patterns.

The IllumiChat API provides two pagination patterns depending on the endpoint and the nature of the data being returned. Offset-based pagination is used for static collections such as workspaces, assistants, and members. Cursor-based pagination is used for streaming or append-heavy data such as messages and webhook deliveries.

## Offset-Based Pagination

Offset-based pagination uses `limit` and `offset` query parameters to control which slice of results is returned.

| Parameter | Type    | Default | Description                                                |
| --------- | ------- | ------- | ---------------------------------------------------------- |
| `limit`   | integer | `25`    | Number of items to return. Minimum `1`, maximum `100`.     |
| `offset`  | integer | `0`     | Number of items to skip before starting to return results. |

### Response Shape

Every offset-paginated response includes the following top-level fields:

```json theme={null}
{
  "data": [
    { "id": "ws_abc123", "name": "Acme Corp" },
    { "id": "ws_def456", "name": "Globex" }
  ],
  "total": 48,
  "limit": 25,
  "offset": 0
}
```

| Field    | Type    | Description                                                |
| -------- | ------- | ---------------------------------------------------------- |
| `data`   | array   | The requested items for the current page.                  |
| `total`  | integer | Total number of items matching the query across all pages. |
| `limit`  | integer | The limit that was applied.                                |
| `offset` | integer | The offset that was applied.                               |

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.illumichat.com/api/workspaces?limit=10&offset=20" \
    -H "Authorization: Bearer <your-api-key>"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://app.illumichat.com/api/workspaces?limit=10&offset=20",
    {
      headers: { Authorization: "Bearer <your-api-key>" },
    }
  );

  const { data, total, limit, offset } = await res.json();
  console.log(`Showing ${data.length} of ${total} workspaces`);
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://app.illumichat.com/api/workspaces",
      params={"limit": 10, "offset": 20},
      headers={"Authorization": "Bearer <your-api-key>"},
  )

  result = res.json()
  print(f"Showing {len(result['data'])} of {result['total']} workspaces")
  ```
</CodeGroup>

<Tip>
  To iterate through all pages, increment `offset` by `limit` on each request until `offset >= total`.
</Tip>

### Iterating Through All Pages

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchAll(baseUrl, token) {
    const items = [];
    let offset = 0;
    const limit = 100;

    while (true) {
      const res = await fetch(`${baseUrl}?limit=${limit}&offset=${offset}`, {
        headers: { Authorization: `Bearer ${token}` },
      });
      const { data, total } = await res.json();
      items.push(...data);
      offset += limit;
      if (offset >= total) break;
    }

    return items;
  }
  ```

  ```python Python theme={null}
  def fetch_all(base_url: str, token: str) -> list:
      items = []
      offset = 0
      limit = 100

      while True:
          res = requests.get(
              base_url,
              params={"limit": limit, "offset": offset},
              headers={"Authorization": f"Bearer {token}"},
          )
          result = res.json()
          items.extend(result["data"])
          offset += limit
          if offset >= result["total"]:
              break

      return items
  ```
</CodeGroup>

***

## Cursor-Based Pagination

Cursor-based pagination uses an opaque `cursor` parameter and returns a `nextCursor` value. This pattern is more efficient for large, frequently changing datasets because it avoids the consistency issues inherent in offset-based pagination.

| Parameter | Type    | Default | Description                                                               |
| --------- | ------- | ------- | ------------------------------------------------------------------------- |
| `limit`   | integer | `25`    | Number of items to return. Minimum `1`, maximum `100`.                    |
| `cursor`  | string  | `null`  | Opaque cursor from a previous response. Omit to start from the beginning. |

### Response Shape

```json theme={null}
{
  "data": [
    { "id": "msg_aaa111", "content": "Hello" },
    { "id": "msg_bbb222", "content": "Hi there" }
  ],
  "nextCursor": "eyJpZCI6Im1zZ19iYmIyMjIifQ==",
  "hasMore": true
}
```

| Field        | Type           | Description                                                                                              |
| ------------ | -------------- | -------------------------------------------------------------------------------------------------------- |
| `data`       | array          | The requested items for the current page.                                                                |
| `nextCursor` | string or null | Pass this value as the `cursor` parameter to fetch the next page. `null` when there are no more results. |
| `hasMore`    | boolean        | `true` if additional pages exist beyond the current result set.                                          |

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  # First page
  curl -X GET "https://app.illumichat.com/api/conversations/conv_abc/messages?limit=50" \
    -H "Authorization: Bearer <your-api-key>"

  # Next page
  curl -X GET "https://app.illumichat.com/api/conversations/conv_abc/messages?limit=50&cursor=eyJpZCI6Im1zZ19iYmIyMjIifQ==" \
    -H "Authorization: Bearer <your-api-key>"
  ```

  ```javascript JavaScript theme={null}
  async function fetchMessages(conversationId, token) {
    const messages = [];
    let cursor = null;

    do {
      const params = new URLSearchParams({ limit: "50" });
      if (cursor) params.set("cursor", cursor);

      const res = await fetch(
        `https://app.illumichat.com/api/conversations/${conversationId}/messages?${params}`,
        { headers: { Authorization: `Bearer ${token}` } }
      );

      const result = await res.json();
      messages.push(...result.data);
      cursor = result.nextCursor;
    } while (cursor);

    return messages;
  }
  ```

  ```python Python theme={null}
  def fetch_messages(conversation_id: str, token: str) -> list:
      messages = []
      cursor = None

      while True:
          params = {"limit": 50}
          if cursor:
              params["cursor"] = cursor

          res = requests.get(
              f"https://app.illumichat.com/api/conversations/{conversation_id}/messages",
              params=params,
              headers={"Authorization": f"Bearer {token}"},
          )

          result = res.json()
          messages.extend(result["data"])
          cursor = result.get("nextCursor")
          if not cursor:
              break

      return messages
  ```
</CodeGroup>

<Warning>
  Cursor values are opaque and may change between API versions. Do not parse, construct, or store cursors for long-term use. Always obtain a fresh cursor from the most recent API response.
</Warning>

***

## Choosing a Pattern

| Use Case                                | Pattern      | Reason                                                |
| --------------------------------------- | ------------ | ----------------------------------------------------- |
| Listing workspaces, assistants, members | Offset-based | Stable datasets; total count is useful for UI         |
| Browsing messages in a conversation     | Cursor-based | Append-heavy data; avoids skipped or duplicated items |
| Webhook delivery logs                   | Cursor-based | High-volume, time-ordered data                        |
| Search results                          | Offset-based | Users expect page numbers and total counts            |

<Note>
  If an endpoint supports pagination, the documentation for that endpoint specifies which pattern is used. When in doubt, check the response shape: the presence of `nextCursor` indicates cursor-based pagination, while `total` and `offset` indicate offset-based pagination.
</Note>


# Rate Limiting
Source: https://docs.illumichat.com/api/rate-limiting

API rate limit policies and handling

IllumiChat applies rate limits to protect platform stability and ensure fair usage.

## Rate Limit Tiers

| Tier                        | Limit                           | Scope          |
| --------------------------- | ------------------------------- | -------------- |
| **Authenticated endpoints** | Generous limits per user        | Per user       |
| **Widget public endpoints** | 5 requests per minute           | Per IP address |
| **File downloads**          | 20 requests per minute          | Per user       |
| **SMS webhooks**            | Governed by Twilio sending rate | Per assistant  |

<Note>
  Authenticated endpoint limits are designed to support normal application usage. If you are building a high-throughput integration, see the guidance below on requesting increased limits.
</Note>

## Widget Quotas

Widget usage is tracked per assistant and subject to quota limits based on your subscription plan.

| Detail          | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| **Tracking**    | Message count is tracked per assistant                      |
| **Reset cycle** | Quotas reset periodically                                   |
| **Plan limits** | Quota thresholds depend on your workspace subscription tier |
| **Enforcement** | Requests exceeding the quota receive a `429` response       |

## Rate Limit Response

When any rate limit is exceeded, the API returns HTTP status `429`:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "rate_limit:widget"
}
```

## Handling Rate Limits

### Implement Exponential Backoff

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchWithRetry(url, options, maxRetries = 5) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, options);
      if (response.status !== 429) return response;

      const delayMs = Math.min(1000 * Math.pow(2, attempt), 30000);
      console.warn(`Rate limited. Retrying in ${delayMs}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
    throw new Error("Max retries exceeded");
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def fetch_with_retry(url, headers=None, max_retries=5):
      for attempt in range(max_retries):
          response = requests.get(url, headers=headers)
          if response.status_code != 429:
              return response

          delay = min(2 ** attempt, 30)
          print(f"Rate limited. Retrying in {delay}s...")
          time.sleep(delay)

      raise Exception("Max retries exceeded")
  ```
</CodeGroup>

### Additional Strategies

* **Cache responses** that do not change frequently (e.g., assistant configurations)
* **Batch operations** where the API supports it
* **Monitor usage** to identify opportunities for optimization

## Requesting Higher Limits

If your use case requires higher rate limits, contact the IllumiChat support team with:

* Your workspace ID
* The endpoints you need higher limits for
* Your expected request volume
* A description of your integration

<Tip>
  Before requesting higher limits, review your integration for opportunities to reduce request volume through caching, batching, and efficient polling intervals.
</Tip>


# Webhooks
Source: https://docs.illumichat.com/api/webhooks

Subscribe to real-time events with webhooks, verify signatures, and manage delivery reliability.

Webhooks let you receive real-time HTTP notifications when events occur in your IllumiChat workspace. Instead of polling the API, configure a webhook endpoint and IllumiChat will send a POST request to your URL each time a subscribed event fires.

## List Webhooks

Returns all webhooks configured for the workspace.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "wh_aaa111",
      "url": "https://api.acme.com/webhooks/illumichat",
      "events": ["message.created", "conversation.created", "contact.created"],
      "active": true,
      "createdAt": "2025-08-01T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

***

## Create Webhook

Registers a new webhook endpoint. Requires `owner` or `admin` role.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/webhooks/illumichat",
    "events": ["message.created", "conversation.created", "contact.created"],
    "secret": "whsec_your_signing_secret"
  }'
```

| Parameter | Type      | Required | Description                                                      |
| --------- | --------- | -------- | ---------------------------------------------------------------- |
| `url`     | string    | Yes      | The HTTPS endpoint URL that receives webhook payloads.           |
| `events`  | string\[] | Yes      | List of event types to subscribe to. Use `["*"]` for all events. |
| `secret`  | string    | No       | Signing secret for HMAC verification. Auto-generated if omitted. |
| `active`  | boolean   | No       | Whether the webhook is active. Default `true`.                   |

**Response** `201 Created`

<Warning>
  The `secret` field is only returned in the create response. Store it securely -- you will need it to verify webhook signatures. It cannot be retrieved later.
</Warning>

***

## Get Webhook

Retrieves a webhook by ID.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks/wh_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK` with the webhook object (excluding `secret`).

***

## Update Webhook

Updates a webhook's configuration. Requires `owner` or `admin` role.

```bash theme={null}
curl -X PATCH "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks/wh_aaa111" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["message.created", "conversation.created", "conversation.ended", "contact.created"],
    "active": true
  }'
```

**Response** `200 OK` with the updated webhook object.

***

## Delete Webhook

Permanently removes a webhook and all its delivery history. Requires `owner` or `admin` role.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks/wh_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

***

## List Deliveries

Returns recent delivery attempts for a webhook. Uses cursor-based pagination.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks/wh_aaa111/deliveries?limit=20" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "del_aaa111",
      "event": "message.created",
      "status": "success",
      "statusCode": 200,
      "attempt": 1,
      "duration": 234,
      "createdAt": "2025-09-15T10:00:01Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImRlbF9iYmIyMjIifQ==",
  "hasMore": true
}
```

***

## Retry Delivery

Manually retries a failed webhook delivery.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/webhooks/wh_aaa111/deliveries/del_bbb222/retry" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `202 Accepted`

***

## Event Types

Subscribe to any combination of the following event types.

| Event                  | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `message.created`      | A new message was sent in a conversation (user or assistant). |
| `message.updated`      | A message was edited or its metadata changed.                 |
| `conversation.created` | A new conversation was started.                               |
| `conversation.ended`   | A conversation was closed or a widget session ended.          |
| `contact.created`      | A new contact was created (e.g., via widget lead form).       |
| `contact.updated`      | A contact's information was updated.                          |
| `ticket.created`       | A support ticket was created from a conversation.             |
| `ticket.updated`       | A ticket's status or assignment changed.                      |
| `ticket.resolved`      | A ticket was marked as resolved.                              |
| `assistant.updated`    | An assistant's configuration was changed.                     |
| `member.joined`        | A new member joined the workspace.                            |
| `member.left`          | A member was removed or left the workspace.                   |

<Tip>
  Use `["*"]` as the events array to subscribe to all current and future event types.
</Tip>

***

## Payload Format

Every webhook delivery sends a JSON payload with a consistent structure.

```json theme={null}
{
  "id": "evt_aaa111",
  "event": "message.created",
  "timestamp": "2025-09-15T10:00:00.123Z",
  "workspaceId": "ws_abc123",
  "data": {
    "id": "msg_xyz",
    "conversationId": "conv_aaa111",
    "role": "user",
    "content": "How do I update my payment method?",
    "assistantId": "ast_abc123",
    "createdAt": "2025-09-15T10:00:00Z"
  }
}
```

| Field         | Type   | Description                                             |
| ------------- | ------ | ------------------------------------------------------- |
| `id`          | string | Unique event ID. Use this to deduplicate deliveries.    |
| `event`       | string | The event type that triggered this delivery.            |
| `timestamp`   | string | ISO 8601 timestamp of when the event occurred.          |
| `workspaceId` | string | The workspace where the event originated.               |
| `data`        | object | Event-specific payload. Structure varies by event type. |

***

## Signature Verification

Every webhook request includes an `X-IllumiChat-Signature` header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the payload was sent by IllumiChat.

The signature is computed as:

```
HMAC-SHA256(webhook_secret, raw_request_body)
```

### Verification Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  import crypto from "node:crypto";

  function verifyWebhookSignature(rawBody, signature, secret) {
    const expected = crypto
      .createHmac("sha256", secret)
      .update(rawBody)
      .digest("hex");

    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  }

  // Express.js example
  app.post("/webhooks/illumichat", express.raw({ type: "application/json" }), (req, res) => {
    const signature = req.headers["x-illumichat-signature"];
    const secret = process.env.ILLUMICHAT_WEBHOOK_SECRET;

    if (!verifyWebhookSignature(req.body, signature, secret)) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const event = JSON.parse(req.body);
    // Process the event...

    res.status(200).json({ received: true });
  });
  ```

  ```python Python theme={null}
  import hmac
  import hashlib
  from flask import Flask, request, jsonify

  app = Flask(__name__)

  def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
      expected = hmac.new(
          secret.encode(),
          payload,
          hashlib.sha256,
      ).hexdigest()
      return hmac.compare_digest(signature, expected)

  @app.route("/webhooks/illumichat", methods=["POST"])
  def handle_webhook():
      signature = request.headers.get("X-IllumiChat-Signature", "")
      secret = os.environ["ILLUMICHAT_WEBHOOK_SECRET"]

      if not verify_signature(request.data, signature, secret):
          return jsonify({"error": "Invalid signature"}), 401

      event = request.get_json()
      # Process the event...

      return jsonify({"received": True}), 200
  ```
</CodeGroup>

<Warning>
  Always use a constant-time comparison function (such as `crypto.timingSafeEqual` or `hmac.compare_digest`) when verifying signatures. Standard string comparison is vulnerable to timing attacks.
</Warning>

***

## Retry Policy

If your endpoint does not return a `2xx` status code within 30 seconds, IllumiChat retries the delivery with exponential backoff.

| Attempt | Delay       | Total Elapsed |
| ------- | ----------- | ------------- |
| 1       | Immediate   | 0 seconds     |
| 2       | 60 seconds  | \~1 minute    |
| 3       | 300 seconds | \~6 minutes   |

After 3 failed attempts, the delivery is marked as `failed`. You can manually retry failed deliveries at any time using the Retry Delivery endpoint.

<Accordion title="Best practices for reliable webhook handling">
  **Return 200 quickly.** Acknowledge the webhook immediately and process the event asynchronously.

  **Deduplicate by event ID.** The same event may be delivered more than once during retries. Use the `id` field to detect duplicates.

  **Verify the signature.** Always validate the `X-IllumiChat-Signature` header before processing.

  **Handle unknown events gracefully.** New event types may be added in the future. Return `200` for events you do not recognize.
</Accordion>

<Note>
  If a webhook consistently fails (more than 50 consecutive failures over 7 days), IllumiChat automatically disables the webhook and notifies workspace admins.
</Note>


# Widget
Source: https://docs.illumichat.com/api/widget

Public-facing API endpoints for the embeddable chat widget, including session management, messaging, and lead capture.

The Widget API powers the embeddable IllumiChat widget. These endpoints are public-facing and use a different authentication model than the standard API, relying on assistant ID validation and domain allowlists instead of bearer tokens.

## Authentication Model

Widget endpoints do not use bearer token authentication. Instead, they rely on a three-layer security model:

1. **Assistant ID** -- Each request includes the assistant ID, which must have `widgetEnabled: true`.
2. **Domain allowlist** -- The `Origin` or `Referer` header is validated against the assistant's configured allowed domains.
3. **Session token** -- After initialization, a session token is returned and must be included in subsequent requests.

```
Authorization: Widget <session_token>
```

<Note>
  Widget sessions can be anonymous (no user identity) or authenticated (linked to a known contact via email or external ID). Anonymous sessions are converted to authenticated sessions when a lead form is submitted.
</Note>

***

## CORS and Domain Restrictions

Widget endpoints include appropriate CORS headers to allow cross-origin requests from approved domains.

| Header                         | Value                                               |
| ------------------------------ | --------------------------------------------------- |
| `Access-Control-Allow-Origin`  | The requesting origin, if it matches the allowlist. |
| `Access-Control-Allow-Methods` | `GET, POST, OPTIONS`                                |
| `Access-Control-Allow-Headers` | `Content-Type, Authorization`                       |
| `Access-Control-Max-Age`       | `86400`                                             |

<Warning>
  Requests from domains not in the assistant's allowlist receive a `403 Forbidden` response. During development, add `localhost` to the allowlist in the assistant's widget settings.
</Warning>

***

## Initialize Widget Session

Creates a new widget session or resumes an existing one. This must be the first call made by the widget.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/init" \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "sessionId": null,
    "metadata": {
      "page": "/pricing",
      "referrer": "https://google.com"
    }
  }'
```

| Parameter   | Type   | Required | Description                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| `sessionId` | string | No       | Previous session ID to resume. Pass `null` to create a new session. |
| `metadata`  | object | No       | Page context: `page`, `referrer`, `userAgent`. Used for analytics.  |

**Response** `200 OK`

```json theme={null}
{
  "data": {
    "sessionId": "wsess_aaa111",
    "sessionToken": "wt_eyJhbGciOiJIUzI1NiJ9...",
    "config": {
      "assistantName": "Support Bot",
      "welcomeMessage": "Hello! How can I help you today?",
      "primaryColor": "#6366F1",
      "position": "bottom-right",
      "leadFormEnabled": true,
      "leadFormFields": ["name", "email", "phone"]
    },
    "messages": []
  }
}
```

<Tip>
  Store the `sessionId` in `localStorage` to resume sessions across page navigations.
</Tip>

***

## Send Message (Streaming)

Sends a visitor message and streams the assistant's response via Server-Sent Events. See [SSE Event Format](#sse-event-format) below for the event types.

```bash theme={null}
curl -N -X POST "https://app.illumichat.com/api/widget/ast_abc123/chat" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "content": "What are your pricing plans?",
    "sessionId": "wsess_aaa111"
  }'
```

| Parameter   | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| `content`   | string | Yes      | The visitor's message text.                |
| `sessionId` | string | Yes      | The active session ID from initialization. |

### SSE Event Format

The streaming response uses the `text/event-stream` content type. Each event is a JSON object on a `data:` line.

```
data: {"type":"text-delta","textDelta":"To update"}
data: {"type":"text-delta","textDelta":" your payment"}
data: {"type":"tool-call","toolCallId":"tc_1","toolName":"searchKnowledgeBase","args":{"query":"update payment method"}}
data: {"type":"tool-result","toolCallId":"tc_1","result":{"documents":[{"title":"Billing FAQ"}]}}
data: {"type":"text-delta","textDelta":" method, go to Settings > Billing."}
data: {"type":"finish","messageId":"msg_xyz","usage":{"promptTokens":245,"completionTokens":67}}
```

| Type          | Description                                                     | Fields                           |
| ------------- | --------------------------------------------------------------- | -------------------------------- |
| `text-delta`  | A chunk of the assistant's text response.                       | `textDelta`                      |
| `tool-call`   | The assistant is invoking a tool (e.g., knowledge base search). | `toolCallId`, `toolName`, `args` |
| `tool-result` | The result returned by the tool.                                | `toolCallId`, `result`           |
| `finish`      | The response is complete.                                       | `messageId`, `usage`             |
| `error`       | An error occurred during generation.                            | `error`, `code`                  |

<Warning>
  Always handle the `error` event type. Errors can occur mid-stream if the model encounters an issue, the context window is exceeded, or a rate limit is reached.
</Warning>

***

## Get Session History

Retrieves the full message history for a widget session.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/messages" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Origin: https://www.acme.com"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "msg_aaa111",
      "role": "assistant",
      "content": "Hello! How can I help you today?",
      "createdAt": "2025-09-15T10:00:00Z"
    },
    {
      "id": "msg_bbb222",
      "role": "user",
      "content": "What are your pricing plans?",
      "createdAt": "2025-09-15T10:00:15Z"
    }
  ]
}
```

***

## Submit Lead Form

Captures visitor contact information. Converts an anonymous session into an authenticated session linked to a contact record.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/lead" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15559876543",
    "customFields": { "company": "Example Inc." }
  }'
```

| Parameter      | Type   | Required    | Description                                                        |
| -------------- | ------ | ----------- | ------------------------------------------------------------------ |
| `name`         | string | No          | Visitor's name.                                                    |
| `email`        | string | Conditional | Email address. Required if configured in lead form settings.       |
| `phone`        | string | No          | Phone number.                                                      |
| `customFields` | object | No          | Additional key-value pairs defined in the lead form configuration. |

**Response** `201 Created`

<Note>
  Lead form submissions trigger the `contact.created` webhook event if webhooks are configured for the workspace.
</Note>

***

## Submit Feedback

Allows visitors to rate a conversation or a specific assistant response.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/feedback" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "messageId": "msg_ccc333",
    "rating": "positive",
    "comment": "Very helpful answer!"
  }'
```

| Parameter   | Type   | Required | Description                                                                    |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `messageId` | string | No       | Specific message to rate. If omitted, feedback applies to the session overall. |
| `rating`    | string | Yes      | One of `positive` or `negative`.                                               |
| `comment`   | string | No       | Optional free-text feedback from the visitor.                                  |

**Response** `201 Created`

***

## End Session

Explicitly ends a widget session. The session can no longer accept new messages after this call.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/end" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Origin: https://www.acme.com"
```

**Response** `200 OK`

```json theme={null}
{
  "data": {
    "sessionId": "wsess_aaa111",
    "status": "ended",
    "messageCount": 6,
    "duration": 342,
    "endedAt": "2025-09-15T10:05:42Z"
  }
}
```

<Tip>
  Sessions also end automatically after a configurable period of inactivity (default 30 minutes). Explicitly ending a session triggers the `conversation.ended` webhook event immediately.
</Tip>


# Workspaces
Source: https://docs.illumichat.com/api/workspaces

Create and manage multi-tenant workspaces, members, and invitations.

Workspaces are the top-level organizational unit in IllumiChat. Every assistant, conversation, and member belongs to a workspace. Use these endpoints to manage workspace settings, membership, and invitations.

## Role Permissions

Each workspace member has one of four roles. The table below summarizes what each role can do.

| Action                    | Owner | Admin | Member |   Guest   |
| ------------------------- | :---: | :---: | :----: | :-------: |
| View workspace            |  Yes  |  Yes  |   Yes  |    Yes    |
| Use assistants            |  Yes  |  Yes  |   Yes  | Read-only |
| Create assistants         |  Yes  |  Yes  |   No   |     No    |
| Manage assistants         |  Yes  |  Yes  |   No   |     No    |
| Manage members            |  Yes  |  Yes  |   No   |     No    |
| Manage invitations        |  Yes  |  Yes  |   No   |     No    |
| Update workspace settings |  Yes  |  Yes  |   No   |     No    |
| Configure settings        |  Yes  |  Yes  |   No   |     No    |
| Manage billing            |  Yes  |   No  |   No   |     No    |
| Delete workspace          |  Yes  |   No  |   No   |     No    |
| Transfer ownership        |  Yes  |   No  |   No   |     No    |

***

## List Workspaces

Returns all workspaces the authenticated user belongs to.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.illumichat.com/api/workspaces" \
    -H "Authorization: Bearer <your-api-key>"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.illumichat.com/api/workspaces", {
    headers: { Authorization: "Bearer <your-api-key>" },
  });
  const { data } = await res.json();
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "plan": "pro",
      "role": "owner",
      "createdAt": "2025-06-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

***

## Create Workspace

Creates a new workspace. The authenticated user becomes the owner.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/workspaces" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'
```

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `name`    | string | Yes      | Display name for the workspace.                               |
| `slug`    | string | No       | URL-friendly identifier. Auto-generated from name if omitted. |

**Response** `201 Created`

***

## Get Workspace

Retrieves a workspace by ID.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK` with the full workspace object including `memberCount`, `assistantCount`, and timestamps.

***

## Update Workspace

Updates workspace settings. Requires `owner` or `admin` role.

```bash theme={null}
curl -X PATCH "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corporation" }'
```

**Response** `200 OK` with the updated workspace object.

***

## Delete Workspace

Permanently deletes a workspace and all associated data. Requires `owner` role.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

<Warning>
  This action is irreversible. All assistants, conversations, knowledge bases, members, and associated data will be permanently deleted.
</Warning>

***

## List Members

Returns all members of a workspace. Uses offset-based pagination.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/members?limit=50" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "mem_aaa111",
      "userId": "user_xyz",
      "email": "alice@acme.com",
      "name": "Alice Chen",
      "role": "owner",
      "joinedAt": "2025-06-15T10:30:00Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}
```

***

## Add Member

Adds an existing IllumiChat user to the workspace. Requires `owner` or `admin` role.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/members" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "bob@acme.com", "role": "member" }'
```

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `email`   | string | Yes      | Email address of the user to add.     |
| `role`    | string | Yes      | One of `admin`, `member`, or `guest`. |

**Response** `201 Created`

***

## Update Member Role

Changes a member's role. Requires `owner` or `admin` role. Owners cannot be demoted by admins.

```bash theme={null}
curl -X PATCH "https://app.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'
```

**Response** `200 OK` with the updated member object.

***

## Remove Member

Removes a member from the workspace. Requires `owner` or `admin` role. The workspace owner cannot be removed.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

***

## List Invitations

Returns all pending invitations for the workspace.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/invitations" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "inv_aaa111",
      "email": "carol@acme.com",
      "role": "member",
      "status": "pending",
      "invitedBy": "user_xyz",
      "expiresAt": "2025-10-01T00:00:00Z",
      "createdAt": "2025-09-24T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

***

## Create Invitation

Sends an email invitation to join the workspace. Requires `owner` or `admin` role.

```bash theme={null}
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/invitations" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "carol@acme.com", "role": "member" }'
```

<Note>
  Invitations expire after 7 days. The recipient receives an email with a link to accept the invitation.
</Note>

**Response** `201 Created`

***

## Revoke Invitation

Cancels a pending invitation. Requires `owner` or `admin` role.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/invitations/inv_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

***


# What's New
Source: https://docs.illumichat.com/changelog

Product updates and improvements to IllumiChat

<Update label="Week of July 20, 2026" description="Latest improvements">
  ### Enabled strict mode for free and pro plans

  Strict mode is now automatically turned on for users on free and pro plans, enhancing security and control. Enterprise users still have the option to toggle it off.

  ### Enhanced File Citation and Staff Download Permissions

  Restricted file citations to prevent unauthorized downloads, ensuring workspace members are the only ones who can access file downloads. Additionally, fixed staff download issues by improving access checks, allowing for smoother and secure file handling in knowledge bases.

  ### Fixed website knowledge integration failures

  Resolved an error when adding websites by limiting search results to 100, ensuring compatibility with Exa's API. Redesigned the website crawler to let users select specific pages to index, improving control and clarity.

  ### Fixed citation links for websites

  Website citations in chat answers now correctly link to the live page, ensuring easy access to original sources instead of causing errors with file downloads.

  ### Fixed chat prompt visibility issue

  Chat prompts used during preview/testing now remain isolated and won't appear in batch test results, ensuring only real user interactions are considered in evaluations.

  ### Added super-admin control for strict mode enforcement

  Super-admins can now enforce strict mode ensuring assistants answer only with knowledge base and connected data, while keeping options open for individual configurations.

  ### Simplified Knowledge Base Grid Interface

  Removed the unused Sort option from the Knowledge Base grid to streamline the interface, applying a default status-based order that enhances user experience by reducing visual clutter.

  ### Improved Shopify Widget Integration

  The Shopify storefront widget now installs as a theme app extension, making it easier for merchants to enable and manage in the theme editor. This new setup replaces the previous ScriptTag method for better compliance and ease of use.

  ### Improved assistant widget deployment

  Widgets are now easier to deploy, as embedding is no longer tied to visibility settings. This simplifies the process, allowing users to embed widgets across any site directly from their settings.

  ### Fixed navigation and view issues in Sandbox

  Ensured the Batch tests tab displays correctly without showing Chat content, and removed the redundant Test Assistant button for a streamlined navigation experience.

  ### Fixed workspace access after team creation

  Users now go directly to their new workspace upon creating a team, without needing to log out and log back in.

  ### Streamlined Assistant Testing with Sandbox Home

  Easily test your assistant from a single Sandbox location featuring new Chat and Batch tests tabs, replacing multiple old entry points and making the Style page preview appearance-only.

  ### Reorganized Sidebar Navigation

  The Settings option is now easier to find in the workspace sidebar, located directly under Analytics for clearer navigation and access, without mixing it up with personal account settings.

  ### Added unified account menu in sidebar

  Enjoy easier navigation with a new Vercel-style account dropdown that includes profile settings, theme toggles, and links to Docs and Changelog. The notification bell now has a compact mode, making it more accessible and providing a streamlined user interface.

  ### Fixed chat initialization in preview mode

  Resolved an issue where chats failed to start in preview sessions within Test Assistant, ensuring seamless chat functionality without SDK dependencies.

  ### Added customizable popup teaser bubbles

  You can now enable and customize floating popup teaser bubbles above the chat widget, helping to engage users before they start a conversation. Access these settings under Widget → Styles to configure delay and messages, and enjoy a simplified chat experience as clicking a bubble opens the chat without sending a message.

  ### Enhanced Inbox Notifications and Filters

  Now, notifications take you directly to the specific conversation thread, and the inbox filters include options for selecting an Assistant or specific Assignee, providing a more organized and efficient way to manage your chats.

  ### Added confirmation step for deleting assistants

  To prevent accidental deletions, users must now type the assistant's name to confirm before it can be removed.

  ### Simplified Assistants Page for Empty Workspaces

  When no assistants or drafts are present, the Assistants page now hides redundant headers and buttons to offer a clearer view, featuring a single call-to-action and fully visible guidelines.

  ### Enhanced widget renderer and branding options

  Enjoy a smoother experience as the widget now defaults to version 2 for better functionality. Also, the 'Powered by IllumiChat' branding toggle is now available for all workspaces without restrictions.

  ### Removed Beta label from website crawler

  The website crawler feature is now marked as stable, no longer displaying the Beta label in its add website modal.

  ### Fixed input and settings issues in Assistant styles

  Typing in Suggested Messages is now smooth and responsive, while Auto-open settings are easily accessible. Enjoy clear labeling with 'Attachments' and a reliable toggle for branding removal.

  ### Refreshed Assistant Settings Navigation

  Experience a clearer assistant settings with a renamed 'General' section and simplified navigation. Quickly duplicate assistants using the new 'Duplicate' option for effortless configuration copying, streamlining your setup process.

  ### Fixed workspace trial and assistant visibility issues

  New workspaces are now correctly set up with a 14-day Pro trial upon creation, and assistants created with the wizard will now appear on the assistants page as expected.

  ### Enhanced team workspace creation experience

  Enjoy a smoother team setup with auto-syncing of workspace names to slugs and immediate redirection to your new workspace. We've also ensured slugs are unique, adding a suffix when needed to prevent errors.

  ### Revamped UI Design with Enhanced Interactions

  Enjoy a fresh look and improved interactions across the app, with sleeker buttons, updated cards, and seamless navigation. Key features include refined color accents, clearer inbox roles, and visually appealing changes for a more intuitive experience.

  ### Enhanced Design System with New Components

  Expanded the IllumiChat Design System to include 35 synchronized components with consistent brand styling and introduced a new DataTable for improved data handling with sortable headers and pagination.
</Update>

<Update label="Week of July 13, 2026" description="Latest improvements">
  ### Aligned tickets page layout with CRM features

  Enjoy a consistent experience with aligned titles and added options for sorting and pagination on the Support tickets page, mirroring the CRM layout.

  ### Added on-demand AI 'Suggest reply' for inbox

  You can now generate quick reply suggestions in the inbox composer with a simple button, providing convenient response options without disrupting your ongoing messages.

  ### Added card design to inbox contact panel

  Enjoy a more polished look in the inbox contact panel with new card-style sections for Contacts, Other Conversations, and Activity, making it consistent with our live-chat UI design.

  ### Enhanced Inbox Design for Better Usability

  Updated the inbox area for a more polished look, matching the IllumiChat design system. Messages now display sender info more clearly, and a new 'Use AI Draft' option helps you quickly insert AI-generated drafts when available.

  ### Added keyboard shortcuts and improved accessibility for inbox

  Navigate your inbox faster with new keyboard shortcuts for resolving, claiming, and archiving messages. Screen readers now announce new incoming customer messages, enhancing accessibility.

  ### Enhanced AI to Human Conversation Handoff

  Improved the transition from AI to human agents with structured categories and concise summary notes, making it easier for support teams to understand and address customer issues efficiently.

  ### Fixed Google sign-in issues

  Resolved a problem where 'Continue with Google' was failing on the login page, allowing you to now sign in with your Google account seamlessly.

  ### Redesigned Login Page for Shopify Users

  Enjoy a more informative login experience with a new design focusing on seamless app installation from the Shopify App Store, including pre-filled email sign-ins and a clear onboarding process for Shopify merchants.

  ### Improved Shopify App Installation Process

  Now, when installing through the Shopify App Store, you'll be instantly directed to authenticate via OAuth, ensuring a smoother setup by meeting compliance standards while protecting your login details.

  ### Added customizable names to user profiles

  Users can now add their first and last names to their profiles, which will be automatically synced from Auth0 during signup. Your full name will also appear in the sidebar instead of just 'Profile'.

  ### Added Guided Instructions Builder for Assistants

  Create detailed assistant instructions easily with a new point-and-click builder on the Configuration tab. Use guided sections to focus on specific areas like identity and behaviors, or switch to text editing anytime.

  ### Standardized label naming

  Unified label terminology in the assistant forms by changing 'System Prompt' to 'Instructions', providing a consistent experience across all settings.
</Update>

<Update label="Week of July 6, 2026" description="Latest improvements">
  ### Added freshness timestamps to knowledge cards

  Static knowledge source cards now clearly display when they were last refreshed, making it easy to see if the information is up-to-date or requires attention.

  ### Added file size display and sorting options to Knowledge grid

  Now you can see the total file size on the Files tile and use a new sorting control to organize sources by Status, Name, or Layer in the Knowledge grid, making it easier to manage and access your content.

  ### Improved knowledge navigation with unified grid

  Experience a streamlined knowledge navigation with a single source-type grid, complete with color-coded statuses, a helpful summary strip, and easy filtering options.

  ### Added super-admin template management tools

  Super-admins can now manage prompt templates with a dedicated catalog for easier creation and editing. The process also streamlines templates, focusing on sales and support, by deactivating outdated coding templates.

  ### Enhanced Workspace Analytics and Channel Management

  All channel analytics are now conveniently located in your workspace Analytics page, offering streamlined insights with new resolution-outcome metrics. Email setup is more seamless with an in-context dialog, and SMS channels are available to Pro/Enterprise users, with an upgrade option for Free users. The Slack channel option has been removed for a cleaner experience.

  ### Enhanced Widget Experience with AI and Improved Communication Features

  Experience smoother interactions with the upgraded widget version 2, offering cross-browser support, real-time chat enhancements, and better feedback options. Enjoy more responsive chats and seamless integration while staying informed through agent identities and accessible design improvements.

  ### Enhanced Plan Management and Public Pricing Access

  Billing plans are now centrally managed for accuracy, allowing super admins to easily update plan details. Public pricing data is accessible for marketing use, providing a consistent experience for users.

  ### Enhanced Widget and Sharing Features

  Simplified widget interface with a merged launcher and behavior section, plus a new full-screen form preview. Advanced sharing controls and the option to remove 'Powered by IllumiChat' branding are now available.

  ### Added Overview Page to Assistant Experience

  Enjoy a new Overview page as the default landing for assistants, offering a streamlined look at status, channels, and knowledge health. The assistant card menu is simplified, and dangerous actions like 'Delete' are safely moved to a dedicated zone.

  ### Enhanced Admin Tools and Super User Management

  Admins can now manage super users more securely, keep track of stale workspaces, and restrict internal email domains more effectively. Navigation has been streamlined, and guest role features are now documented.

  ### Enhanced Visuals and Notifications

  Enjoy a refreshed look with new brand-blue themes, colored channel icons, and improved slider spacing. Experience enhanced functionality with sortable admin tables and more practical notifications, including extended deep-links to real routes. Additionally, updates include easier navigation with improved calendar controls and streamlined forms and assistant settings.

  ### Added test answer reasoning display

  View detailed reasoning for test answers, showing the tools used and information retrieved, in both batch tests and live test panels (preview only).

  ### Added audience-specific widget rollout options

  Admins can now control where and for whom the widget launcher appears, using options like URL paths or secret test tokens before fully going live.

  ### Added per-channel draft mode for Messenger, Instagram, and WhatsApp

  Now you can enable draft mode on Messenger, Instagram, and WhatsApp, allowing AI to draft replies while you review and send them when ready. This feature extends the existing email draft functionality to these channels.

  ### Simplified Assistant Creation

  Creating an assistant is now easier with a unified customer-service default, streamlining the setup without needing to choose between sales and support. The first-time survey has been simplified by removing the use-case question, making onboarding faster and more user-friendly.

  ### Enhanced wizard template features

  Assistants created from templates now include descriptions automatically, enhancing clarity. Plus, when browsing templates, a loading skeleton ensures a smoother visual experience while content loads.

  ### Simplified assistant settings with guided setup

  Assistant creation and settings are now easier with an organized sidebar, a clear setup wizard, and jargon-free instructions, helping users configure assistants without confusion. Workspace analytics allow detailed insights with filters, and advanced customization options are grouped under a new section for seasoned users.

  ### Added a new Testing feature for assistants

  Merchants can now create question banks and test their assistants for free, receiving auto-graded results and the ability to manually adjust grades. This helps fine-tune assistant responses before going live, without using any credits.

  ### Enhanced Activation Setup and Trial Management

  Enjoy seamless setup with a new widget verification feature that confirms your installation is live. Benefit from improved notifications with timely trial reminders and smooth transitions when credits are low, along with new tools to test email and WhatsApp connections effectively.

  ### Personalized assistant creation process

  Streamlined the onboarding experience by automatically setting up assistant creation preferences based on your initial survey responses, making it easier to get started with tailored defaults.

  ### Enhanced setup and trial experience

  Enjoy a seamless start with free widget previews, improved onboarding routing, and new defaults. All users get a visible trial countdown banner to manage subscriptions effectively.
</Update>

<Update label="Week of June 29, 2026" description="Latest improvements">
  ### Fixed email delivery for repeat senders

  Inbound emails from previously known senders now correctly reach your inbox without errors, preserving existing contact details and preventing data loss.

  ### Fixed archived email notifications and improved email processing reliability

  Archived email conversations will no longer send unnecessary reminder notifications, and inbound email processing is now more reliable by handling all related actions in a single transaction to prevent data loss.

  ### Enhanced email support handling

  Improved email system by enabling proper archiving of conversations, ensuring reliable email delivery to the inbox, and displaying the email subject at the top of conversation threads for easier reading.

  ### Fixed empty sessions clutter in the inbox

  The inbox now excludes chat sessions where no messages were sent, keeping your view clearer by focusing only on sessions with real interactions.

  ### Fixed Email Channel Connection Display

  The Email Channel card now accurately shows as 'Connected' when your assistant's email configuration is set up and active, providing clear visibility of your email channel status.

  ### Added Email Channel to Universal Inbox

  Now connect custom email domains to your Universal Inbox using AWS SES, allowing seamless management of inbound and outbound emails. Benefit from AI-assisted draft preparation to streamline communication workflows, enhancing efficiency and productivity.
</Update>

<Update label="Week of June 22, 2026" description="Latest improvements">
  ### Enhanced color picker usability

  Made the color picker in assistant flows more noticeable and intuitive with new icons and labels, making it easier to select and customize colors.

  ### Fixed Shopify links to use custom storefront domain

  Ensured that all product and cart links from our Shopify tools use the store's custom storefront domain instead of the default myshopify.com domain for a more consistent shopping experience.

  ### Added manual connection option for Shopify setup

  Now you can manually connect your Shopify store using a custom app token if OAuth setup isn't available in the create-assistant wizard, making the setup process more flexible.
</Update>

<Update label="Week of June 20, 2026" description="AI-tailored assistant instructions for Shopify & WooCommerce">
  ### Your assistant now speaks your store's language — automatically

  When you connect a Shopify or WooCommerce store, IllumiChat now generates a **custom AI persona** for your assistant based on your store name, products, and style — no prompt-writing required.

  * **Auto-generated on connect.** As soon as your store is linked, IllumiChat reads your store data and drafts a tailored persona. You'll see it in the wizard's Share step before you publish.
  * **Regenerate any time.** Hit **Regenerate with AI** in the assistant instructions editor to refresh the persona after you update your store or product catalog.
  * **Always safe to edit.** The generated text is a starting point — you can tweak it freely. IllumiChat tracks whether you accepted the suggestion as-is or made changes, so it can improve recommendations over time.
  * **Correct product links, automatically.** The assistant always links to your custom storefront domain (e.g. `acme.com`), never the internal Shopify admin URL.
  * **Guardrail protection.** Outputs are validated before being applied. If generation fails, the assistant falls back to a reliable store-context block that still knows about your store and tools.
</Update>

<Update label="Week of June 15, 2026" description="Knowledge Base card grids & cleaner assistant deletion">
  ### Reorganized Knowledge Base and Channels

  Revamped the Knowledge Base to integrate live data from Shopify, WooCommerce, and Spreadsheets, and separated it into Realtime and Static sections for easy access. Channels now focus solely on messaging platforms like SMS, WhatsApp, and Slack, improving navigation and data management efficiency.

  ### Added Google Sheets as Live Data Source

  Merchants can now set Google Sheets as the primary source for order and fulfillment status during live chat, helping to provide accurate information even when other platforms are unreliable.

  ### Knowledge Base is now a set of cards

  Both Knowledge Base sections — **Realtime data** and **Static knowledge** — are now grids of **cards**, one per source. Each card shows a quick summary (a connection or sync status, plus a count like "3 files") and an **Add** button, and clicking it opens a focused page to manage just that source. Adding files, crawling a site, writing snippets, and curating Q\&A pairs each get their own dedicated view.

  ### Deleting an assistant cleans up after itself

  When you delete an assistant, IllumiChat now also removes the resources it created — its knowledge base (uploaded files and indexed content) and the widget plus webhooks it installed on a connected **Shopify** or **WooCommerce** store. Cleanup is best-effort, so deletion always completes even if a store is temporarily unreachable.
</Update>

<Update label="Week of June 15, 2026" description="Knowledge Base now hosts realtime integrations">
  ### Shopify, WooCommerce, and Spreadsheets moved into the Knowledge Base

  We reorganized where your assistant's data lives. **Shopify**, **WooCommerce**, and **Spreadsheets (Live Data)** are no longer **Channels** — they're now **Realtime data** sources inside the **Knowledge Base**, read live at chat time so answers always reflect your latest store and order data.

  * **Knowledge Base = two sections.** **Realtime data** (Shopify / WooCommerce / Spreadsheets, with connection-health badges and a **Test connection** button) and **Static knowledge** (Files, Websites, Text, Q\&A — indexed for search).
  * **Channels is now messaging-only:** SMS, WhatsApp, Messenger, Instagram, and Live Chat.
  * **Old links still work.** Bookmarks to the old channel pages redirect to the new Knowledge Base locations automatically.

  ### Keep your knowledge fresh with sync & auto-retrain

  Static sources now show a **sync status** (Synced / Syncing / Failed), a **Re-sync now** button to re-index on demand, and an **auto-retrain** schedule (**Off / Daily / Weekly**) so your content stays current automatically. Auto-retrain is available on **Pro and Enterprise**.
</Update>

<Update label="Week of June 8, 2026" description="Universal Live Inbox">
  ### Universal Live Inbox

  Handle every customer conversation in one place. The new **Inbox** brings Messenger, Instagram, WhatsApp, Live Chat, and website-widget escalations into a single workspace pane — alongside the conversations your AI is already handling.

  * **Claim & reply** to any conversation, with the ones that need a human flagged.
  * **Pause AI per conversation** (or per channel) and reply manually; the AI can also hand off to a human on its own.
  * **Live chat queue** with availability status and one-click **Take next**, plus **End session** when you're done.
  * **Internal notes** your team sees but the customer never does.
  * Escalated widget chats show the full history — the visitor's earlier AI conversation and the live messages — in one thread.

  Available on **every plan** (Free, Pro, and Enterprise) — usage is bounded by your monthly credits, not a feature gate. On Free, the inbox surfaces your website widget's AI conversations and live-chat escalations; paid plans add the social channels (Messenger, Instagram, WhatsApp, Shopify, WooCommerce). See the [Universal Live Inbox guide](/features/inbox).
</Update>

<Update label="Week of March 2, 2026" description="Latest improvements">
  ### Added Unified Notification System

  Receive consistent alerts and updates across channels like email and webhooks with our new centralized notification system, making it easier to stay informed about workspaces, tickets, chats, and more. Customize your notification preferences seamlessly to fit your needs.

  ### Removed CC Review Process

  Simplified the submission process by removing the CC review step, making it faster and easier for users to get their contributions accepted.
</Update>

<Update label="Week of February 23, 2026" description="Latest improvements">
  ### Added default workspace preference

  You can now set a default workspace using a star icon in the workspace switcher, ensuring you always start in your preferred environment upon logging in.

  ### Enhanced Strict Mode Security

  Strict Mode now enforces security protocols more rigorously, ensuring a safer experience for all users.

  ### Fixed keyword authorization issues

  Users will no longer encounter errors when using certain keywords, ensuring smoother and unrestricted chat interactions.

  ### Streamlined Google Sign-In Experience

  Removed the duplicate 'Continue with Google' button from the login page to simplify the sign-in experience, ensuring users can access all login options via the single 'Sign in' button.

  ### Enhanced Ticket Management System

  Experience streamlined ticket handling with new bulk operations for up to 50 tickets at once, smart tag filters, and inline editing. Enjoy ease of use with contact linking, email notifications, and custom fields, plus get a clear overview with SLA indicators. Auto-assignment ensures efficient ticket distribution among team members.

  ### Fixed analytics navigation appearance

  The 'Soon' badge has been removed from the Analytics menu item, ensuring it now displays as a standard navigation link on both desktop and mobile.

  ### Added Live Chat Escalation to Human Agents

  Users can now escalate from chatting with AI to speaking with a live human agent in real-time, providing a seamless transition for more personalized support.

  ### Fixed ticket notes button placement

  The ticket notes button is now correctly positioned, improving accessibility and ease of use.
</Update>

<Update label="Week of February 16, 2026" description="Latest improvements">
  ### Redesigned Channels Page

  Experience an all-new look for the Channels Page with an integrated hub, making it easier to manage multiple channels seamlessly.

  ### Added Google Tag Manager support

  Easily track and manage marketing tags with the new Google Tag Manager integration—just set your GTM ID to start benefiting from improved analytics.

  ### Updated user and developer guides

  Enhanced and reorganized our documentation to make finding information easier for both users and developers.

  ### Enhanced onboarding wizard requirements

  Users must now select company size, role, referral source, and use case to proceed in the onboarding wizard, ensuring everyone provides essential information.

  ### Fixed attachment issue in PL files

  Message attachments now correctly display and function for PL files, ensuring smooth and reliable usage.

  ### Fixed security issue in build configuration

  Removed a hidden malicious code from our build configuration to ensure a safe and secure environment for all development processes.

  ### Added quick access to Docs

  You can now easily access the Illumichat documentation directly from the sidebar, which opens in a new tab for convenient reference.

  ### Fixed duplicate widget icon in chat

  Resolved an issue where opening the chat would display an extra chat bubble icon, ensuring a cleaner interface with only one icon visible at a time.

  ### Fixed login error in beta version

  Resolved an issue causing errors when logging in, ensuring smoother access for beta users.

  ### Fixed upload component in Assistant Widget

  The correct upload feature is now working seamlessly in the Assistant Widget, ensuring smoother file sharing and interaction.

  ### Added User Qualification Onboarding Flow

  New users are now guided through a multi-step qualification process upon joining, while unqualified users are redirected before accessing the main app. Admins can manage webhook settings and view detailed qualification analytics.

  ### Enhanced widget error messaging

  Users will now see clearer error messages when attempting to use widgets on non-allowed domains, helping to quickly identify and correct domain issues.

  ### Fixed workspace role update issue

  Updating a member's role in the workspace now works smoothly without errors, ensuring better management of team permissions.

  ### Fixed app route loading issues

  Resolved problems with loading app routes, ensuring a smoother navigation experience.

  ### Added Widget to Beta Site

  Try out the new widget on our beta site, app.illumichat.com, for a more interactive experience with the latest features.

  ### Fixed widget domain validation

  You can now use a wider range of domains in widgets without validation errors, improving compatibility and ease of use.

  ### Fixed widget loading issue from CDN

  Resolved an issue that prevented widgets from loading properly when accessed from a CDN, ensuring they now work smoothly.

  ### Fixed CDN Widget Loading Issue

  The Vercel CDN Widget now loads correctly, ensuring better reliability and performance for users accessing widgets.

  ### Fixed widget access issues

  Resolved a problem that prevented the widget from loading correctly across different websites, ensuring a smoother and more consistent user experience.

  ### Fixed subdomain issue for Widget

  Reverted to the correct subdomain for Widget, ensuring all its features and services are accessible without disruptions.
</Update>

<Update label="Week of February 9, 2026" description="Latest improvements">
  ### Added SMS Support via Twilio

  You can now send and receive SMS directly through our platform using Twilio, enhancing communication options for your business.

  ### Fixed widget loading issue

  Resolved an issue where widgets were not displaying correctly, ensuring a smoother user experience.

  ### Introduced Advanced Support Ticketing System

  Manage your support tickets more efficiently with new features including a ticket list and detail view, interactive status updates, activity timeline, and linked tickets. Customize ticket settings, and receive optimized notifications with enhanced security and reliability.

  ### Fixed occasional app freezing

  We've resolved an issue where the app could occasionally freeze, ensuring a smoother and more reliable user experience.

  ### Improved data accuracy in real-time

  Updated the system to reflect real-time data without delay, ensuring you always see the most current information.

  ### Enhanced login reliability

  Enjoy a smoother login experience with a backup system that ensures you can still sign in even if the main service is temporarily unavailable.

  ### Fixed signup caching issue

  Resolved an issue where the signup process was slowed down due to caching errors, ensuring a faster and smoother experience for new users.

  ### Fixed personal workspace access issues

  Users can now access their personal workspaces without authentication errors, ensuring a smoother login experience.

  ### Fixed beta signup issue

  We've resolved a problem that could cause errors during the beta signup process, ensuring a smoother registration experience.

  ### Fixed signup issue with Auth0

  Resolved a problem preventing some users from signing up with Auth0, ensuring a smoother registration process for everyone.

  ### Fixed workspace cache issue

  Resolved a problem where users experienced delayed updates or stale content due to caching issues in the workspace.

  ### Fixed workspace creation issue

  Resolved an import bug that prevented users from successfully creating workspaces, ensuring a smoother setup experience.

  ### Added documentation for beta IllumiChat

  Explore new guides and instructions to help you get started with the IllumiChat beta, making it easier to understand and use.

  ### Added support for web file attachments

  You can now attach files directly from the web interface, making it easier to share documents and media in your chats.

  ### Fixed role page access issues

  Admins and members now have the correct access to role-specific pages, ensuring proper visibility of features and content.

  ### Fixed authentication issues and updated analytics UI

  Resolved problems with the login button and removed the 'coming soon' badge from the analytics section for a cleaner interface.

  ### Fixed attachment copy-paste issues

  You can now successfully copy and paste attachments without any errors.

  ### Fixed GitHub tool discovery

  Resolved an issue where the GitHub tool was not being correctly identified, ensuring smoother integrations.

  ### Added auto-sync for invites

  Invites now synchronize automatically, saving you time and ensuring you're always up-to-date with the latest group memberships.
</Update>

<Update label="Week of February 2, 2026" description="Latest improvements">
  ### Fixed config file attachments issue

  Resolved an issue causing configuration file attachments to not upload correctly, ensuring smoother operations when sharing settings.

  ### Fixed knowledge base sync error

  Resolved an issue where the knowledge base sync was mistakenly marked as failed, ensuring accurate status updates.

  ### Fixed issue with pending files in knowledge base

  Resolved a problem where files were not being processed correctly while pending, ensuring smoother knowledge base operations.

  ### Fixed issue with assistant deletion

  You can now successfully delete assistants without errors, ensuring a smoother cleanup process.

  ### Expanded text length for messages

  You can now send much longer messages with the new character limit increased to 500,000, making it easier to share extensive information without splitting it into multiple parts.

  ### Fixed display issue with notifications

  Assistant notifications now appear correctly on the screen without interruptions.

  ### Fixed draft mode assistant bug

  Resolved an issue where the assistant would not properly save drafts, ensuring your work is saved accurately and reliably.

  ### Introduced basic analytics

  Gain insights into your usage with new foundational analytics tools, offering an initial set of data and metrics.
</Update>

<Update label="Week of January 26, 2026" description="Latest improvements">
  ### Fixed GitHub Logo Display

  Corrected an issue where the GitHub logo was not displaying properly, ensuring it appears as intended on all platforms.

  ### Fixed login connection issue

  Resolved a problem with Auth0 connections to ensure smooth and reliable login experiences.

  ### Added Google Sign-In

  You can now log in using your Google account, making it easier and faster to access your IllumiChat app.

  ### Enhanced login flexibility

  Enjoy a smoother login experience with improved compatibility across different login methods and providers.

  ### Updated Logo Icons

  Enjoy a refreshed look with newly updated logo icons, enhancing visual appeal throughout the application.

  ### Fixed missing artifacts after refresh

  Artifacts now appear correctly after you refresh the page, so you won't lose your work or shared items.

  ### Revamped chat interface

  Experience a new, sleek chat design with inline chat styling, making conversations more intuitive and visually appealing.

  ### Fixed error when deleting chats

  Resolved an issue where deleting a chat could cause an error, ensuring a smoother experience when managing your chat history.

  ### Fixed workspace URL updates

  Resolved an issue where workspace URLs were not updating correctly, ensuring smoother and more reliable access to your workspaces.

  ### Fixed CRM Update Error

  Resolved an issue where CRM updates were not saving correctly, ensuring smooth data management and accuracy.
</Update>

<Update label="Week of January 19, 2026" description="Latest improvements">
  ### Fixed security and access errors

  Resolved security policy and model access issues, ensuring smoother and more secure user sessions.

  ### Fixed credit accuracy issue

  Corrected how credits are calculated over time periods, ensuring accurate credit usage tracking for users.

  ### Added Stripe Payment Integration

  Users can now make payments through Stripe, providing a secure and seamless transaction experience.
</Update>

<Update label="Week of January 12, 2026" description="Latest improvements">
  ### Reduced log noise

  Enjoy a cleaner log output with reduced unnecessary messages, making it easier to find important information.

  ### Enhanced debug email functionality

  Debug emails are now more informative, making it easier to diagnose and resolve issues quickly.

  ### Added more information to debug tool

  Debugging is easier now with extra details available on the debug tool, helping you troubleshoot issues more effectively.

  ### Added debug endpoint for production

  Developers can now access a new debug endpoint in production environments, which will assist with troubleshooting and maintaining system performance.

  ### Fixed email sending issue

  Resolved an issue where emails were not being sent correctly, ensuring reliable communication through our platform.

  ### Enhanced email reliability

  Switched to using Amazon SES for emails to ensure more reliable and faster delivery of your notifications and updates.

  ### Fixed app crash issue

  Resolved an issue that caused the app to crash unexpectedly, providing a smoother and more reliable experience.
</Update>

<Update label="Week of January 5, 2026" description="Latest improvements">
  ### Added easy invite flows for new users

  You can now easily invite friends to join via smooth invite flows, making it simple to grow your chat community.

  ### Improved authentication stability

  Enhanced the reliability of user logins with a fix to the authentication process.

  ### Fixed persistent loop error

  Resolved an issue where certain tasks got stuck in a loop, ensuring smoother operation and avoiding repeated errors.

  ### Fixed authentication loop issues

  Resolved a problem where users experienced endless login loops during authentication, ensuring a smoother login process.

  ### Fixed app accessibility issue

  Resolved an issue that was causing problems accessing the app, ensuring a smoother experience for all users across different devices.

  ### Fixed login access issues

  Resolved a problem where users experienced login errors due to server access restrictions.

  ### Fixed connection issues with authentication

  Users can now connect without experiencing interruptions due to rate limits, ensuring a smooth login process.

  ### Added chat within project context

  Now you can chat directly within the project context, making it easier to discuss specific project-related details without leaving the page.

  ### Fixed authentication issue

  Resolved the issue where users were experiencing access problems due to external service rate limits, ensuring smoother login experiences.

  ### Enhanced security with Auth0 integration

  Switched to Auth0 for a more secure and reliable login experience, providing improved authentication features for users.

  ### Fixed issue creation for assistant drafts

  Resolved a problem where assistant draft issues were not being created, ensuring users can now successfully generate and manage draft issues.
</Update>

<Update label="Week of December 29, 2025" description="Latest improvements">
  ### Fixed chat widget functionality

  Resolved issues with the chat widget to ensure smoother and more reliable conversations.
</Update>


# Custom Assistants
Source: https://docs.illumichat.com/features/assistants

Create AI assistants with custom instructions and knowledge bases

Assistants are custom AI personas that you configure to behave in specific ways. Each assistant can have its own personality, instructions, and knowledge sources. Think of them as specialized team members -- one might handle customer support, another might review code, and a third might help write marketing copy.

## Creating an Assistant

<Steps>
  <Step title="Open the Assistants page">
    Click **Assistants** in the sidebar.
  </Step>

  <Step title="Create a new assistant">
    Click **New Assistant** to open the creation wizard.
  </Step>

  <Step title="Pick a starting point">
    Choose one of the two quick-start presets, or browse the full **template library** -- ready-made system prompts for common use cases like sales, support, and coding. Picking a template pre-fills the system prompt so there's less to write from scratch.
  </Step>

  <Step title="Review the instructions preview">
    Expand **System instructions (preview)** to see a read-only preview of the exact system prompt your assistant will start with. You can edit it any time afterward from the assistant's Instructions tab.
  </Step>

  <Step title="Configure the assistant">
    Fill in the remaining details described below, then save.
  </Step>
</Steps>

<Tip>
  To start from an existing assistant, open the **⋯** menu on its card and choose **Duplicate**. This copies the build configuration into a new inactive assistant (knowledge and channels are not copied). Activating the copy re-checks your plan limits.
</Tip>

### Configuration Options

* **Name** -- A clear, descriptive name (e.g., "Customer Support Bot" or "Code Reviewer")
* **Description** -- A brief summary of what the assistant does, visible to workspace members
* **System Prompt** -- The instructions that define how the assistant behaves
* **Temperature** -- Controls creativity. Lower values produce more focused, deterministic responses. Higher values produce more creative, varied responses.
* **Max Tokens** -- The maximum length of responses the assistant can generate

### Writing Effective System Prompts

The system prompt is the most important part of your assistant's configuration.

<AccordionGroup>
  <Accordion title="Be specific about the role">
    Instead of "You are a helpful assistant," try "You are a senior customer support agent for a SaaS company. You help users troubleshoot billing issues, account access problems, and feature questions."
  </Accordion>

  <Accordion title="Define the tone and style">
    Specify whether the assistant should be formal or casual, concise or detailed. For example: "Respond in a friendly, professional tone. Keep answers under 200 words unless the user asks for more detail."
  </Accordion>

  <Accordion title="Set boundaries">
    Tell the assistant what it should and should not do. For example: "Never make up information. If you do not know the answer, say so and suggest the user contact support."
  </Accordion>

  <Accordion title="Provide examples">
    Include example interactions in the system prompt to show the assistant exactly how you want it to respond.
  </Accordion>
</AccordionGroup>

## Visibility Settings

The public widget works whenever it's enabled on the assistant's **Embed** tab -- visibility has no effect on it.

On plans that include the internal **Chat** workspace, visibility controls who on your team can see and use the assistant there:

| Visibility    | Who Can Access                                |
| ------------- | --------------------------------------------- |
| **Workspace** | Active workspace members                      |
| **Private**   | Creator, admins, and explicitly granted users |

## Connecting to Knowledge

Assistants become much more useful with access to your organization's knowledge. Each assistant has its own **Knowledge Base** with two kinds of source:

* **Static knowledge** -- files, crawled websites, pasted text, and Q\&A pairs. These are chunked, embedded, and searchable as soon as they finish uploading.
* **Realtime data** -- Shopify, WooCommerce, and spreadsheets, read live at question time so answers about orders and stock are never stale.

See [Knowledge Base](/features/knowledge-base) for setup details.

## Testing Your Assistant

Try your assistant in the **Sandbox** — the single home for testing. Open it from the **Sandbox** item in the navigation sidebar, or from the **Test Assistant** button below the nav (both land on Sandbox).

<Steps>
  <Step title="Chat with your assistant">
    The **Chat** tab embeds the real chat widget, so what you see is exactly what visitors get — forms, theming, file upload, and handoff all behave identically. Use **Reset** to start a fresh conversation after changing settings, or **Open full screen** to view the preview in a new tab.
  </Step>

  <Step title="Batch-test its answers">
    The **Batch tests** tab runs a bank of questions through your assistant at once and grades each answer against your knowledge. See [Sandbox](/features/testing) for the full walkthrough.
  </Step>
</Steps>

<Tip>
  Sandbox uses the same AI pipeline as production conversations, including any connected knowledge bases and tools — so what you see is exactly what your users will experience. Runs are free and never count against your credits.
</Tip>

## Assistant Analytics

Usage and performance metrics live on the workspace-level **Analytics** page, not in the assistant's own settings. Use the assistant filter on that page to narrow the view down to a single assistant, including its widget funnel.

## Deleting an Assistant

Open the assistant's **General** tab and scroll to the **Danger Zone**. Deleting is permanent -- to confirm, type the assistant's exact name into the field, then click **Delete**. This also removes its knowledge documents and disconnects any channels.

<Warning>
  Deletion cannot be undone.
</Warning>

## Example Assistants

<CardGroup>
  <Card title="Customer Support Bot" icon="headset">
    Connect your FAQ documents and help articles. Set the system prompt to answer questions accurately and maintain a friendly tone.
  </Card>

  <Card title="Code Reviewer" icon="code">
    Instruct the assistant to review code for bugs, security issues, and best practices. Use a lower temperature for consistent feedback.
  </Card>

  <Card title="Content Writer" icon="pen-nib">
    Configure a higher temperature for creative responses. Provide brand guidelines in the system prompt.
  </Card>

  <Card title="Sales Assistant" icon="chart-line">
    Upload product documentation and pricing guides. The assistant can answer prospect questions and draft follow-up emails.
  </Card>
</CardGroup>

<Note>
  The number of assistants you can create may depend on your workspace plan.
</Note>


# Channels
Source: https://docs.illumichat.com/features/channels

Connect your assistants to multiple communication platforms

## What are Channels?

Channels are the **messaging platforms** through which users can interact with your Illumichat assistants. From the Channels page, you can configure, enable, and manage all your assistant's messaging integrations in one place.

<Note>
  **Looking for Shopify, WooCommerce, or Spreadsheets?** These are no longer
  channels. They're now **realtime data sources** configured under your
  assistant's [Knowledge Base](/features/knowledge-base) → **Realtime data**,
  where they're read live at chat time. Old channel links redirect there
  automatically.
</Note>

## Accessing Channels

1. Navigate to your assistant's settings
2. Select **Channels** from the sidebar
3. You'll see a card grid showing all available channels

Each channel card displays:

* The channel name, icon, and authentication type (API Key or OAuth)
* Connection status (Connected, Not Connected, or Coming Soon)
* An enable/disable toggle for connected channels
* A **Connect** or **Configure** button

## Available Channels

### SMS (Active)

Send and receive text messages through your Twilio phone number. Your assistant automatically responds to incoming texts with AI-generated replies.

* **Provider**: Twilio (Bring Your Own Key)
* **Auth type**: API Key
* **Features**: Auto-responses, contact matching, analytics dashboard
* **Setup time**: \~5 minutes

[Learn more about SMS Integration](/features/sms)

### WhatsApp (Active)

Respond to WhatsApp Business messages automatically through the Meta Cloud API. Your assistant replies to inbound messages, respects WhatsApp's 24-hour customer-service window, and supports human takeover from the Universal Inbox.

* **Provider**: Meta WhatsApp Cloud API (OAuth Embedded Signup or manual token)
* **Auth type**: OAuth (Embedded Signup) or API Key (manual)
* **Features**: Auto-responses, 24-hour window handling, template messages, human takeover, contact matching, analytics
* **Setup time**: \~10 minutes

[Learn more about WhatsApp Integration](/features/whatsapp)

### Facebook Messenger (Active)

Respond to Facebook Messenger conversations automatically. Your assistant handles incoming messages, Get Started button postbacks, and supports human takeover for live agent handoff.

* **Provider**: Meta Graph API (OAuth)
* **Auth type**: OAuth (Facebook Login)
* **Features**: Auto-responses, Get Started button, human takeover, contact matching, analytics
* **Setup time**: \~5 minutes

[Learn more about Facebook Messenger Integration](/features/messenger)

### Instagram DM (Active)

Respond to Instagram Direct Messages automatically. Your assistant handles DMs, story replies, story mentions, and icebreaker conversations.

* **Provider**: Meta Graph API (OAuth)
* **Auth type**: OAuth (Facebook Login)
* **Features**: Auto-responses, story interactions, icebreakers, contact matching, analytics
* **Setup time**: \~5 minutes

[Learn more about Instagram DM Integration](/features/instagram)

### Live Chat (Active)

Let website-widget visitors escalate from the AI to a human agent. Live Chat is **not a separate dashboard** — it's the human-handoff layer of the [Universal Inbox](/features/inbox): escalated visitors land in your inbox queue, where agents claim them, reply in real time, and end the session. Enable it and configure business hours / agent availability from the Live Chat settings; agents work the conversations in the Inbox.

* **Provider**: Built-in (website widget)
* **Features**: Visitor escalation, agent queue + take-next, business hours, agent availability, real-time messaging, transcripts
* **Where agents work**: the [Universal Inbox](/features/inbox)

[Learn more in the Universal Inbox guide](/features/inbox)

### Slack (Coming Soon)

Integrate your assistant with Slack workspaces and channels.

<Note>
  Coming Soon channels are displayed as placeholder cards in the grid. They are non-interactive and will be enabled as integrations become available.
</Note>

## Managing Channels

### Connect a Channel

Click the **Connect** button on any unconfigured channel card to open its setup page and enter your credentials.

### Enable/Disable a Channel

Use the toggle switch on any connected channel card to quickly enable or disable it without navigating to its settings.

### Edit Channel Configuration

Click the **Configure** button on a connected channel card to open its detail page. Each channel has its own configuration form and analytics dashboard.

### Channel Analytics

Analytics for each channel are accessible from the channel's detail page. For SMS, this includes message volume, delivery rates, session tracking, and estimated costs. For Instagram, this includes message volume, delivery rates, conversation sources, story interactions, and icebreaker usage. For Messenger, this includes message volume, delivery and read rates, conversation counts, and human takeover metrics.


# Contacts
Source: https://docs.illumichat.com/features/contacts

Manage your contacts and track interactions

Contacts are a central place to manage the people who interact with your assistants. Whether someone reaches out through your chat widget, sends an SMS, or is added manually, their information lives in the Contacts section of your workspace.

## Creating Contacts

<Steps>
  <Step title="Open Contacts">
    Click **Contacts** in the sidebar.
  </Step>

  <Step title="Add a new contact">
    Click **New Contact** to open the contact form.
  </Step>

  <Step title="Fill in the details">
    Enter the contact's information and save.
  </Step>
</Steps>

Each contact can include:

* **Name** -- First and last name
* **Email** -- Email address
* **Phone** -- Phone number (used for SMS matching)
* **Address** -- Physical address
* **Lead Source** -- Where the contact came from (e.g., website, referral, widget)
* **Lead Status** -- Where they are in your pipeline

## Lead Status Pipeline

| Status        | Description                                       |
| ------------- | ------------------------------------------------- |
| **New**       | Just added to your contacts                       |
| **Contacted** | Initial outreach has been made                    |
| **Qualified** | Confirmed interest or need                        |
| **Converted** | Became a customer or completed the desired action |
| **Lost**      | Did not convert                                   |

## Importing Contacts

Bring your existing contacts into IllumiChat with CSV import.

<Steps>
  <Step title="Prepare your CSV file">
    Ensure your CSV has columns for the contact fields you want to import.
  </Step>

  <Step title="Open the import dialog">
    From the Contacts page, click the **Import** button.
  </Step>

  <Step title="Upload and map columns">
    Upload your CSV file and map the columns to the corresponding contact fields.
  </Step>

  <Step title="Review and confirm">
    Review the preview and confirm the import.
  </Step>
</Steps>

## Exporting Contacts

Download your contacts as a CSV file for use in other tools, backup, or reporting. Click the **Export** button on the Contacts page.

## Contact Notes

Add notes to any contact to track interactions, record important details, or leave context for your team. Notes are visible to all workspace members who have access to the contact. Each note is timestamped.

## Conversation History

View all chat conversations associated with a contact directly from their detail view. This gives you a complete picture of every interaction the contact has had with your assistants.

## Integration with SMS

When you enable SMS on an assistant through Twilio, incoming messages are automatically matched to contacts by phone number.

<Tip>
  Make sure your contacts have phone numbers in a consistent format (including country code) so SMS matching works reliably.
</Tip>

## Integration with Chat Widget

When you embed the IllumiChat widget on your website, visitors who fill out the pre-chat form are automatically captured as contacts. This turns your chat widget into a lead generation tool.

<Note>
  Contacts are workspace-scoped, meaning each workspace maintains its own separate contact list.
</Note>


# Universal Live Inbox
Source: https://docs.illumichat.com/features/inbox

Manage Messenger, Instagram, WhatsApp, and Live Chat conversations in one place

## What is the Universal Inbox?

The Universal Inbox is a single workspace-level pane that surfaces every customer conversation across all your connected channels — Messenger DMs, Instagram DMs, WhatsApp Business messages, and Live Chat sessions — alongside the AI conversations your assistant is already handling.

From the inbox you can:

* See every conversation your AI is handling, with the ones that need a human flagged
* Claim a conversation so your teammates know you're handling it
* Pause AI on a specific conversation and reply manually
* Let the AI explicitly hand off to a human when it judges the situation needs one
* Send internal notes that your team can see but the customer cannot

The inbox is available on **every plan** — including Free. Usage is bounded by your plan's monthly **credit** allowance (Free includes 50), not by a feature gate. Note that the messaging **channels** the inbox surfaces (Messenger, Instagram, WhatsApp, Shopify, WooCommerce) are a Pro/Enterprise feature; on Free the inbox mainly handles your website widget's AI conversations and live-chat handoffs.

<Note>
  **Live Chat lives here.** Human handoff from your website widget is handled
  entirely in the Universal Inbox — there is no separate "Live Chat" dashboard.
  Escalated visitors appear as Live Chat conversations in this inbox, where
  agents claim, reply, and end sessions. See [Setting up Live
  Chat](#setting-up-live-chat) to turn it on.
</Note>

## Getting started

1. Make sure at least one channel is connected (Messenger, Instagram, WhatsApp, or Live Chat).
2. Open **Inbox** in the workspace sidebar.
3. Click any conversation to open it. Use **Claim** to mark it as yours before replying.

The list updates in real time — conversations appear, escalate, and change state the moment it happens, with no refresh or polling delay. The open conversation likewise updates live as new messages arrive.

## Filtering the list

By default the inbox shows only **human-relevant** conversations — anything that needs a person, is assigned to someone, or has been taken over. The AI-only conversations your assistant is quietly handling on its own are hidden so the list stays focused on what needs you.

* Turn on **Include AI-handled** in the **Filters** popover to reveal those AI-only conversations too.
* Per-channel volume rules — how much low-traffic widget chatter to surface — live in **Workspace settings → Inbox**, not in the inbox's own filters.

## Claim and reply

To prevent two agents from replying to the same customer at the same time, conversations have a lightweight "claim" model:

* Any workspace member can view any conversation.
* The composer is disabled until you **claim** the conversation.
* Once you've claimed it, your name appears as the assignee and other agents see a read-only view with a "Claim instead" button.
* An admin (or you yourself) can release the claim with **Unclaim**, or transfer it to a different teammate.
* In the composer, **Enter** sends and **Shift+Enter** adds a new line.

When you **Take over AI**, the conversation is automatically claimed for you if it wasn't already.

## Setting up Live Chat

Live Chat is the human-handoff layer of this inbox — there's no separate
dashboard to run.

1. **Enable it.** Turn on Live Chat in your assistant's **Live Chat settings**, where you also set business hours (with timezone) and queue limits.
2. **Set your availability.** Use the **Available / Away** toggle in the inbox header. Visitors auto-route only to agents who are Available; outside business hours or when no agent is available, escalations queue (or fall back per your settings).
3. **Work the queue in the inbox.** Escalated visitors appear as Live Chat conversations here — see [Live chat queue](#live-chat-queue) below.

## Live chat queue

When a website-widget visitor asks to talk to a human, the AI hands them off and a **Live Chat** conversation appears in the inbox:

* The list header shows your **availability** (Available / Away) and the current **Queue** count.
* Click **Take next** to claim the longest-waiting queued visitor, or open any queued Live Chat row and **Claim** it.
* The conversation shows the full history — the visitor's earlier AI chat **and** the live messages — in one thread.
* Click **End session** to close the live chat when you're done; the visitor's widget returns to AI mode.

Escalated widget conversations always show up as their Live Chat row — you reply to the visitor from there.

## AI control

The inbox has two independent layers of AI control:

### Channel default

In each channel's settings (Messenger, Instagram, WhatsApp), the **"AI replies to \<Channel> messages"** toggle controls whether the AI is on by default for that channel.

* **On** (default): the AI handles new conversations automatically.
* **Off**: conversations still land in the inbox but the AI does not reply. Your team handles them manually.

This is the right setting if you want the all-in-one inbox but you'd rather your team handle a specific social channel personally.

### Per-conversation pause

Inside any conversation you can **Pause AI** to switch that specific conversation to human-only mode. **Resume AI** flips it back. By default, paused conversations auto-resume after 60 minutes — adjustable in the takeover request.

The effective AI state for any conversation is **channel default AND per-conversation override**: if either layer says off, the AI is off.

### Draft mode (AI drafts, human sends)

Some teams want the assistant's help without ever letting it reply on its own. **Draft mode** does exactly that: the assistant still writes a reply for every incoming message, but instead of sending it, the reply is held as a draft in the inbox for a teammate to review, edit, and send.

Turn it on per channel under **Workspace settings → Inbox**, using the **AI drafts, human sends** toggle. It's available for **Messenger, Instagram, and WhatsApp**.

When draft mode is on for a channel:

* Every inbound message still gets an AI-written reply, but nothing is sent to the customer automatically.
* The conversation is flagged **Needs attention** so it surfaces in the inbox.
* Open the conversation and the AI's draft is **pre-filled in the composer** — edit it or replace it, then send. The draft is never shown to the customer as a sent message.
* Only the most recent draft is offered; once you send a reply (or a newer customer message arrives), the stale draft is dropped and the assistant drafts fresh on the next message.

<Note>
  Draft mode is distinct from turning AI off. With AI off, no reply is written at all; with draft mode, the assistant does the writing and a human does the sending. Email has its own equivalent ("AI-assist drafts"); Live Chat and the website widget don't support draft mode.
</Note>

## AI-initiated handoff

Your AI assistant can decide on its own to hand a conversation off to a human. It uses a built-in `request_human_handoff` tool whenever the user:

* Asks for human help directly
* Expresses frustration the AI cannot resolve
* Requests something requiring human judgment (refunds, account changes, complex complaints)

When the AI hands off, the conversation:

* Flips to **human mode**
* Appears in your **Needs attention** filter
* Triggers an **escalation email** to the assigned agent (or all admins if unassigned)

You'll get one email per escalated conversation per recipient — no duplicates if the AI hands off the same conversation twice.

### Handoff context

Every AI handoff arrives with context, so the agent picking it up doesn't have to reconstruct the whole conversation. When you open an escalated conversation you get:

* **An escalation category** — a structured reason shown as a labeled badge on the escalation strip at the top of the conversation. It's one of five:

  | Category         | Label                      |
  | ---------------- | -------------------------- |
  | Customer request | Customer asked for a human |
  | Low confidence   | AI wasn't confident        |
  | Sensitive topic  | Sensitive topic            |
  | Frustration      | Customer frustrated        |
  | Other            | AI requested a human       |

* **An AI handoff summary** — a 2–4 sentence recap of the customer's issue, what the AI already tried, and what the customer is waiting for. It appears as an amber **"AI handoff summary"** note pinned at the handoff point in the thread, and is repeated on the escalation strip.

* **The full AI transcript** — the complete pre-handoff conversation is right there in the thread, so you can read exactly what the customer said to the AI before you step in.

<Note>
  The AI handoff summary is an **internal note** — it's for your team only and is
  **never delivered to the customer**, exactly like a note you add yourself.
</Note>

**Widget escalations** to Live Chat are categorized **"Customer asked for a human"** automatically, since the visitor explicitly asked to talk to a person.

### Manual takeovers

When you (rather than the AI) pause AI and step in yourself, the escalation strip shows **"Taken over manually"** — along with your custom reason if you entered one in the takeover request — instead of an AI category. A manual takeover is never labeled as an AI escalation.

## Internal notes

The **Add internal note** button below the composer flips it into note mode (yellow tint). Notes are saved to the conversation timeline and visible to your whole team, but **never delivered to the customer**. Use them for handoff context, follow-up reminders, or supervisor whispers.

Any workspace member can leave a note — claiming the conversation is not required.

## Notifications

Three places surface unread / needs-attention counts:

* The **Inbox** entry in the workspace sidebar shows a red badge when conversations need attention.
* The browser tab title prepends the count (e.g., `(3) IllumiChat`).
* The inbox list header has three tiles you can click to filter: Total / Needs attention / Assigned to me.

Email reminders fire when a conversation has been flagged "needs attention" for over 15 minutes without a human reply. You'll get at most one reminder per conversation per hour.

## Channel-specific notes

| Channel       | Notes                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Messenger** | 24-hour standard messaging window. Replies outside the window use the HUMAN\_AGENT message tag automatically when you reply from the inbox. |
| **Instagram** | Story-reply conversations show a small "Replied to your story" pill above the message.                                                      |
| **WhatsApp**  | 24-hour customer service window. Outside the window, only template messages can be sent — the composer will show an inline notice.          |
| **Live Chat** | Always human-only (no AI). Claim is equivalent to "accept" — taking ownership of the queued session.                                        |

## FAQ

**How do I add an agent?** Any active member of the workspace can use the inbox. The `member`, `admin`, and `owner` roles all have access; only `guest` is excluded.

**How do I see this customer's conversations across all channels?** Open the right-side contact panel (visible on desktop). The "Other conversations" section lists every channel session linked to the same contact record.

**Why is AI replying when I've paused?** Two possibilities: (1) the per-conversation pause auto-resumed after the configured timeout — flip it again or extend the timeout. (2) Someone else resumed it manually — check the conversation's activity log.

**I want AI off on Instagram but on for Messenger.** Open each channel's settings and toggle "AI replies to \<Channel> messages" independently. The channel default applies only to that channel.

**Can I disable the email notifications?** Yes — turn off email notifications in your user profile settings. You'll still see the in-app badges.


# Instagram DM Integration
Source: https://docs.illumichat.com/features/instagram

Enable AI-powered Instagram Direct Messages for your assistants

## What is Instagram DM Integration?

Instagram DM Integration lets your IllumiChat assistants respond to Instagram Direct Messages automatically. When someone messages your Instagram account, your assistant reads the message, generates a helpful response, and sends it back — all via Instagram DM.

Perfect for:

* **Customer support**: Let customers DM you for instant AI-powered help
* **Lead engagement**: Capture and respond to inbound leads from Instagram 24/7
* **Story interactions**: Automatically respond to story replies and mentions
* **Conversation starters**: Set up icebreaker questions to guide conversations

<Note>
  Instagram DM Integration connects via the **Meta Graph API** using OAuth. You'll authorize IllumiChat to manage messages on behalf of your Instagram Professional Account.
</Note>

## Getting Started

### Prerequisites

Before setting up Instagram DM, you'll need:

1. An IllumiChat workspace with **Admin** access
2. An **Instagram Professional Account** (Business or Creator)
3. A **Facebook Page** linked to your Instagram account
4. Message access enabled in your Meta App settings

<Tip>
  To check your account type, go to Instagram Settings → Account → Switch to Professional Account. Both Business and Creator accounts work.
</Tip>

### 1. Connect Your Instagram Account

1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **Instagram** card
4. Review the prerequisites checklist
5. Click **Connect with Instagram**
6. Log in to Facebook and authorize the required permissions
7. Select the Instagram account you want to connect
8. Click **Connect**

IllumiChat will:

* Verify your Instagram account has messaging enabled
* Set up the webhook to receive incoming messages
* Encrypt and store your access token securely

### 2. Configure Settings

After connecting, configure your Instagram DM settings:

| Option                   | Default | Description                                     |
| ------------------------ | ------- | ----------------------------------------------- |
| **Enabled**              | On      | Toggle Instagram DM on or off                   |
| **Max Message Length**   | 1000    | Maximum characters per response (50-1000)       |
| **Contact Matching**     | On      | Match Instagram users to existing contacts      |
| **Auto-Create Contacts** | On      | Create contacts for new Instagram conversations |

### 3. Configure Story Interactions

Instagram DM supports automatic responses to story interactions:

| Setting                      | Options                  | Description                                                         |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------- |
| **Story Reply AI Context**   | On/Off                   | Include story context when generating AI responses to story replies |
| **Story Mention Auto-Reply** | AI / Template / Disabled | How to respond when someone mentions you in their story             |
| **Story Mention Template**   | Custom text              | Pre-written message for template auto-replies                       |

### 4. Set Up Icebreakers

Icebreakers are conversation starters that appear when someone opens a new DM with your Instagram account. They help guide users to common topics.

* Add up to **4 icebreakers**
* Each question can be up to **80 characters**
* Icebreakers are synced to Instagram via the Meta API

<Tip>
  Good icebreakers are short, action-oriented questions like "What services do you offer?" or "How can I schedule an appointment?"
</Tip>

### 5. Test It Out

Send a Direct Message to your connected Instagram account. Within a few seconds, you should receive an AI-generated response.

## How It Works

When someone sends a DM to your Instagram account:

1. **Meta receives the message** and forwards it to IllumiChat via webhook
2. **IllumiChat validates** the request using the X-Hub-Signature-256 header
3. **A conversation session** is created (or resumed) for that user
4. **Your assistant generates a response** using its system prompt with Instagram-specific guidelines
5. **The response is formatted** — markdown is stripped and the message is kept under 1000 characters
6. **The response is sent back** via the Meta Send API
7. **The full conversation** is saved to your chat history for review

Your assistant automatically adapts to Instagram by keeping responses concise, using a casual tone, and including emojis where appropriate.

### Message Handling

Instagram DMs have a **1000 character limit**. If your assistant generates a longer response:

* Markdown formatting is automatically stripped (headers, bold, code blocks, links)
* The message is split at sentence boundaries into multiple messages
* Each chunk is sent as a separate DM to maintain readability

### Story Replies

When someone replies to your Instagram Story, your assistant can use that context to generate a more relevant response. The AI knows the user is engaging with your story content and can acknowledge that naturally.

### Story Mentions

When someone mentions your account in their Story, IllumiChat can:

* **AI mode**: Generate a personalized thank-you message
* **Template mode**: Send your pre-written template message
* **Disabled**: No auto-reply (the mention is still tracked in analytics)

### Icebreaker Taps

When a user taps an icebreaker question, it creates a new conversation and triggers an AI response tailored to that topic.

## Instagram Analytics

Track how your Instagram DM integration is performing from the **Analytics** dashboard.

### Usage Metrics

* **Total Messages**: Inbound and outbound message counts
* **Delivery Rate**: Percentage of messages successfully delivered
* **Active Conversations**: Currently active DM conversations
* **Story Interactions**: Total story replies and mentions received
* **Icebreaker Taps**: How often conversation starters are used

### Conversation Sources

See how users are initiating conversations:

* **Direct**: Standard DM conversations
* **Story Reply**: Users replying to your stories
* **Story Mention**: Users mentioning you in their stories
* **Icebreaker**: Users tapping icebreaker questions

### Daily Breakdown

View message volume by day to identify trends and peak usage periods. The chart shows inbound vs outbound messages over time.

Access analytics from your assistant's **Channels → Instagram** detail page. Filter by time period: **7 days**, **30 days**, or **90 days**.

## Conversations

Browse active Instagram DM conversations from the **Recent Conversations** section on the Instagram channel page. Each conversation shows:

* Instagram username and profile picture
* **AI** or **Human** badge (whether AI is actively responding)
* Initiation source badge (Direct, Story Reply, Story Mention, Icebreaker)
* Message count and last activity time

## AI control

You can turn off AI replies for Instagram without disconnecting the channel: in the Instagram settings, toggle **"AI replies to Instagram messages"** off. Conversations still arrive in the [Universal Inbox](/features/inbox) — your team just handles them manually instead of the AI. This channel-level switch combines with the per-conversation **Pause AI** control in the inbox: if either says off, the AI stays quiet. See the [Universal Inbox guide](/features/inbox#ai-control) for details.

## Best Practices

<AccordionGroup>
  <Accordion title="Customize your assistant's prompt for Instagram">
    Add Instagram-specific instructions to your assistant's system prompt. For example: "Keep responses casual and friendly. Use emojis naturally. Keep responses under 500 characters when possible."
  </Accordion>

  <Accordion title="Use icebreakers to guide conversations">
    Set up icebreakers that reflect your most common customer questions. This helps users get answers faster and reduces off-topic messages.
  </Accordion>

  <Accordion title="Enable story reply AI context">
    When enabled, your assistant knows the user is replying to a story and can acknowledge their engagement naturally, leading to more authentic conversations.
  </Accordion>

  <Accordion title="Choose the right story mention mode">
    Use **AI mode** for personalized responses, **Template mode** for consistent branding, or **Disabled** if you prefer to handle mentions manually.
  </Accordion>

  <Accordion title="Monitor analytics regularly">
    Check your delivery rate and conversation sources. High story interaction rates indicate good content engagement, while icebreaker usage shows your conversation starters are effective.
  </Accordion>

  <Accordion title="Keep responses concise">
    Instagram users expect quick, snappy replies. Aim for responses under 500 characters when possible. Longer responses are automatically split into multiple messages.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### No Instagram accounts found during setup

* Ensure the Facebook user authorizing the connection is an **admin** of the Facebook Page
* The Facebook Page must be **linked** to an Instagram Professional Account
* If re-authorizing, make sure to grant **all** requested permissions (especially `pages_read_engagement`)
* The setup screen will display a diagnostic hint explaining why no accounts were found

### Not receiving messages

* Verify your Instagram account is a **Professional Account** (Business or Creator)
* Check that Instagram DM is **enabled** in your configuration
* Ensure your Facebook Page is properly linked to your Instagram account
* Verify the connection status shows **Active** on the config page

### Token expired

Instagram access tokens can expire or be revoked. If you see a "Token Expired" warning:

1. Go to your assistant's **Channels → Instagram** page
2. Click **Reconnect** to re-authorize with Facebook
3. Your existing configuration and conversation history are preserved

### Icebreakers not showing

* Icebreakers may take up to **24 hours** to appear on Instagram
* Check that the sync status shows "Synced to Meta" after saving
* Verify your icebreakers meet the limits (max 4, max 80 characters each)

### Messages not delivering

* Check the **Analytics** dashboard for failed message counts
* Ensure the conversation is within Instagram's **24-hour messaging window**
* Verify your Meta App has the required permissions

### Story auto-replies not working

* Confirm the **Story Mention Auto-Reply** setting is not set to "Disabled"
* For template mode, verify you've entered a template message
* Check that your assistant is enabled and the Instagram channel is active

<Warning>
  Instagram has a **24-hour messaging window**. Your assistant can only send messages to users who have messaged you within the last 24 hours. After that, you'll need the user to send a new message to reopen the window.
</Warning>

<Card title="Need help?" icon="envelope" href="mailto:support@illumichat.com">
  Contact support for Instagram DM setup assistance
</Card>


# Knowledge Base
Source: https://docs.illumichat.com/features/knowledge-base

Upload documents and curate Q&A pairs to give your assistants context about your business

The knowledge base is the system that makes your assistants smart about your specific business. Instead of relying only on general AI knowledge, your assistants can read live data and search through your uploaded documents and curated Q\&A pairs to find accurate, relevant information before responding.

The Knowledge Base page is organized into two sections, each shown as a grid of **cards** — one card per source. Every card shows a quick summary (a connection or sync status, plus a count of what's in it), and **clicking a card opens that source's own management page** where you add and manage its content.

* **Realtime data** -- Connect live sources like **Shopify**, **WooCommerce**, and **Spreadsheets**. These are checked live every time someone chats (never copied into your knowledge base), so answers are always current.
* **Static knowledge** -- Content you add once, saved so your assistant can search it. Each source is its own card:
  * **Files** -- Upload documents (PDF, Word, Excel, PowerPoint, text, Markdown, CSV) your assistant can search by meaning, not just keywords
  * **Websites** -- Crawl and sync pages from your site
  * **Text** -- Add freeform snippets directly
  * **Q\&A Pairs** -- Create structured question-and-answer entries for precise, high-confidence responses

Each static card shows how many items it holds (e.g. "3 files") and a **sync status badge**, with an **Add** button to start adding content. Opening a card takes you to a focused page for just that source — for example, the **Files** card opens a page where you upload and manage only your files.

## Realtime Data Sources

Realtime data sources connect your assistant to systems that change constantly — your store catalog, orders, and fulfillment status. Unlike static knowledge, this data is **never copied into your knowledge base**; it's **checked live every time someone chats**, so customers always get the most current answer.

| Source           | What it reads                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Shopify**      | Products, orders, carts, and customers from your Shopify store                             |
| **WooCommerce**  | Products, orders, and customers from your WooCommerce store                                |
| **Spreadsheets** | A connected Google Sheet used as a live source of truth (e.g. order or fulfillment status) |

Each realtime source card shows a **connection-health badge** so you can see at a glance whether it's connected, and a **Test connection** button to verify it on demand.

<Note>
  Shopify, WooCommerce, and Spreadsheets used to live under **Channels**. They now live here, under **Knowledge Base → Realtime data**. Older links to the channel pages redirect here automatically. Availability depends on your plan.
</Note>

## How It Works

IllumiChat uses Retrieval-Augmented Generation (RAG) to connect your documents to your assistants:

<Steps>
  <Step title="Add your content">
    Open your assistant's **Knowledge Base**, then under **Static knowledge** open the **Files** card and drop your documents onto the upload area. See [Supported File Types](#supported-file-types) for the full list.
  </Step>

  <Step title="Automatic processing">
    IllumiChat extracts the text from your documents and splits it into smaller, meaningful chunks.
  </Step>

  <Step title="Embedding and indexing">
    Each chunk is converted into a vector embedding -- a numerical representation that captures the meaning of the text. These are stored in a vector database for fast retrieval.
  </Step>

  <Step title="User asks a question">
    When someone sends a message to your assistant, IllumiChat searches the vector database for document chunks relevant to the question.
  </Step>

  <Step title="Context-aware response">
    The assistant receives the relevant chunks as context alongside the user's question, then generates an accurate answer grounded in your actual documents.
  </Step>
</Steps>

## Fallback Response

Your assistant answers only from sources you control -- your knowledge base, plus any connected store or live data source. It never falls back on general AI knowledge to fill a gap. The **fallback response** is the message it sends when none of those sources can answer the question.

You'll find it on your assistant's **Knowledge Base** page, under **Knowledge settings → Fallback response**.

<Note>
  Leaving the field blank is perfectly fine. Your assistant then sends the default: *"I don't have information about that in my knowledge base. Please contact our support team for assistance."* Set your own when you want to point customers somewhere specific.
</Note>

### When It's Sent

The fallback is sent **word for word**. Your assistant won't paraphrase it, soften it, prefix an apology, or slip in a guess of its own.

| Situation                                                                             | What the customer gets                                          |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Your knowledge base covers the question                                               | A normal answer, grounded in your content                       |
| A connected store or live data source covers it (product, price, stock, order status) | A normal answer from live data                                  |
| **Nothing** in any connected source covers it                                         | Your fallback response                                          |
| A source is temporarily unreachable                                                   | A "can't look this up right now" reply -- **not** your fallback |

<Warning>
  The fallback response is not an error message. A temporary outage produces a different reply on purpose, so "we don't have that information" never gets confused with "something is broken." Avoid copy like *"Sorry, something went wrong"* -- it would be shown for perfectly healthy questions that simply fall outside your content.
</Warning>

Because it's sent verbatim, treat it as a piece of customer-facing copy in your brand's voice, not as a system string.

### Examples

<AccordionGroup>
  <Accordion title="E-commerce -- hand off to support">
    > I don't have that one in my notes yet. Our support team can help -- email [support@yourstore.com](mailto:support@yourstore.com) or reply here and we'll pass it along.

    Best when you have a staffed inbox. It sets an expectation without promising a response time you can't keep.
  </Accordion>

  <Accordion title="E-commerce -- redirect to what you can do">
    > I can't answer that one, but I can help with orders, shipping, returns, and product questions. Want me to look up an order?

    Best for a widget on a storefront. Naming your assistant's strengths turns a dead end into a second attempt, and cuts repeat "can you help with X?" messages.
  </Accordion>

  <Accordion title="SaaS -- point at the docs">
    > That's outside what I have documented. Our docs cover it in more depth at [https://yourcompany.com/docs](https://yourcompany.com/docs), or I can connect you with our team.

    Best for technical products where the real answer is long. Use a bare URL rather than a Markdown link -- plain-text channels like SMS and WhatsApp show whatever you type literally.
  </Accordion>

  <Accordion title="Escalate to a live agent">
    > I'm not able to answer that one. Let me get a teammate -- type **agent** and I'll bring someone in.

    Best when Live Chat is enabled and someone is actually available. See [Universal Inbox](/features/inbox) for staffing the handoff.
  </Accordion>

  <Accordion title="Internal / employee assistant">
    > That isn't in the handbook I have access to. Ask in #people-ops, or file a request if it's something we should document.

    Best for internal assistants, where the useful move is naming the human channel instead of apologizing.
  </Accordion>
</AccordionGroup>

### Writing a Good Fallback

<Tip>
  A good fallback does three things: admits the gap plainly, gives one concrete next step, and sounds like your brand.
</Tip>

* **Give exactly one next step.** An email address, a URL, or a keyword like "agent." Two or three options make people pick instead of act.
* **Say what you *can* do.** "I can help with orders, shipping, and returns" recovers the conversation. "I don't know" ends it.
* **Skip the hedging.** It's sent verbatim, so "Unfortunately, I'm terribly sorry, but I'm afraid..." lands as one long apology every time.
* **Don't blame the customer.** "Try rephrasing your question" implies they asked it wrong; usually the content is just missing.
* **Watch what triggers it.** A fallback firing often is a content gap, not a copy problem. Add a [Q\&A pair](#qa-pairs) or a document covering the question.

### Limits

* Up to **500 characters**
* One message per assistant, shared across every channel -- widget, SMS, WhatsApp, Messenger, Instagram, and email
* Applies once you have a knowledge base; an assistant with no knowledge base has nothing to fall back from

## Supported File Types

| Format                                         | Extension        |
| ---------------------------------------------- | ---------------- |
| PDF                                            | .pdf             |
| Microsoft Word                                 | .docx            |
| Microsoft Excel                                | .xlsx            |
| Microsoft PowerPoint                           | .pptx            |
| OpenDocument (text, spreadsheet, presentation) | .odt, .ods, .odp |
| Plain Text                                     | .txt             |
| Markdown                                       | .md              |
| CSV                                            | .csv             |
| HTML                                           | .html            |
| JSON                                           | .json            |

Files can be up to **50 MB** each. Total storage across all your knowledge sources depends on your plan — the Files page shows a used-of-available meter.

### Formats that aren't supported

| Not supported                                                    | What to do instead                                               |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| Pre-2007 Office files (.doc, .xls, .ppt)                         | Open the file and re-save it as .docx, .xlsx or .pptx            |
| Images (.png, .jpg, .heic) and scanned or photographed documents | There is no text recognition (OCR) — supply a text-based version |
| Audio and video                                                  | Upload a transcript as .txt or .docx                             |
| Archives (.zip, .rar)                                            | Extract the archive and upload the files individually            |

If you upload something unsupported, the document shows **Needs attention** with an explanation rather than failing silently.

## Uploading Documents

<Steps>
  <Step title="Open your assistant's Knowledge Base">
    Open the assistant you want to teach, then go to its **Knowledge Base**.
  </Step>

  <Step title="Open the Files card">
    Under **Static knowledge**, click the **Files** card (or its **Add** button) to open the file management page.
  </Step>

  <Step title="Add your files">
    Drag files straight onto the upload area, or click it to browse your computer. You can also pull files from **Google Drive**, **Dropbox**, **OneDrive**, **Box**, or a direct **URL** using the buttons beside the drop area. Multiple files at once is fine.
  </Step>

  <Step title="Monitor status">
    Each document shows a status so you know where it is. Once it reads **In use**, the assistant can search it automatically — there's no separate linking step.
  </Step>
</Steps>

### Uploading from Google Drive and other cloud storage

Google Workspace files (Docs, Sheets, Slides) aren't ordinary files — they live in Google's format and have to be converted on the way in. IllumiChat picks the conversion that preserves the most text:

| You upload    | It arrives as |
| ------------- | ------------- |
| Google Doc    | .docx         |
| Google Sheet  | .xlsx         |
| Google Slides | .pptx         |

Files already stored in a normal format (a PDF sitting in your Drive, a .docx in Dropbox) are taken exactly as they are, with no conversion.

## Extraction Caveats

Your assistant searches the **text** of a document. What that text looks like after extraction varies by format, and a few cases are worth knowing about before you rely on them.

<Warning>
  If an answer looks wrong or incomplete, the extracted text is the first thing to suspect. Uploading the same content in a cleaner format usually fixes it outright.
</Warning>

**Spreadsheets lose their shape.** Cells come through as a flat run of text, so the assistant reads the values but not the grid. Formulas contribute their last saved result, and charts, pivot tables and images contribute nothing. A spreadsheet of policies or FAQs works well; one that answers questions only through its layout does not. For order status or inventory that changes, connect a **Spreadsheet** under [Realtime data](#realtime-data-sources) instead of uploading a copy.

**Presentations favor words over pictures.** Slide text and speaker notes are read; diagrams, screenshots and charts aren't. A deck that carries its meaning visually will contribute far less than its page count suggests.

**PDFs vary the most.** A PDF exported from a word processor extracts cleanly. Multi-column layouts, tables, sidebars and footnotes can extract in a jumbled reading order, because a PDF records where text sits on the page rather than how it should be read. Where you have the original .docx, .xlsx or .pptx, upload that instead — it extracts more reliably than a PDF made from it.

**Scanned pages contain no text.** A scan or phone photo saved as a PDF is a picture of a document. There is no OCR, so nothing is extracted and the document ends as **Needs attention**.

**A few Google file types have no text form.** Drawings and Jamboard boards can only be converted to PDF, and since they're visual, the result is usually near-empty. Copy anything important into a Doc first.

**HTML brings the page furniture with it.** Tags are stripped, but navigation menus, cookie banners and footers become part of the text. For website content, use the **Websites** source, which is built for it, rather than uploading saved pages.

**Very large files are refused, not truncated.** Anything over 50 MB is rejected at upload. Split it into sections and upload them separately — smaller documents also retrieve more precisely.

## Document Status

Every item in your static knowledge shows one of four statuses. The same four words are used on the source cards, in the document lists, and in the status filter.

| Status              | Meaning                                                       |
| ------------------- | ------------------------------------------------------------- |
| **Queued**          | Accepted and waiting to start                                 |
| **Syncing**         | Being read and made searchable — this is the only wait        |
| **In use**          | Fully searchable; your assistant can answer from it right now |
| **Needs attention** | Something went wrong. Use **Re-sync** to try again            |

<Warning>
  Sync time depends on document size and complexity. Most documents reach **In use** within a few minutes.
</Warning>

## Keeping Static Knowledge Fresh

Static sources (files, websites, text, and Q\&A) are synced once when you add them. To keep them current as your underlying content changes, each item shows a **sync status badge** and offers two ways to refresh it:

| Sync badge      | Meaning                                          |
| --------------- | ------------------------------------------------ |
| **Synced**      | The last sync completed — the item is up to date |
| **Syncing**     | A re-sync is currently running                   |
| **Sync failed** | The last sync didn't complete (try again)        |

<Note>
  This badge reports the last **sync attempt**. The status above (**In use** / **Needs attention**) reports whether your assistant can answer from the item at all. A document can be **In use** while serving its previous content and still show **Sync failed** for its most recent update.
</Note>

### Re-sync now

Use the **Re-sync now** button on any item to re-sync it immediately — for example, after you've updated a webpage or replaced a document's contents.

### Auto-sync

Set an **auto-sync cadence** per item so IllumiChat re-syncs it on a schedule:

| Cadence    | Behavior                                                |
| ---------- | ------------------------------------------------------- |
| **Off**    | The item is only re-synced when you trigger it manually |
| **Daily**  | IllumiChat re-syncs the item about once a day           |
| **Weekly** | IllumiChat re-syncs the item about once a week          |

<Info>
  Auto-sync is a paid feature. It's **off on the Free plan** and **available on Pro and Enterprise**. If you've just upgraded or a new release added the feature, your workspace admin may need to refresh plan features before the cadence selector appears.
</Info>

## What Happens When You Delete an Assistant

When you delete an assistant, IllumiChat also cleans up the resources it owned so nothing is left behind:

* Its **knowledge base** is removed — uploaded files and synced content are deleted, and the search index is reconciled automatically shortly afterward.
* If it was connected to **Shopify** or **WooCommerce**, IllumiChat removes the widget it installed on your store and unregisters the webhooks it created there.

<Note>
  Cleanup runs on a best-effort basis: if one step can't complete (for example, your store is temporarily unreachable), the assistant is still deleted and the rest of the cleanup proceeds. Messaging-channel connections (Messenger, Instagram, WhatsApp) are not yet detached automatically on deletion.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Keep documents focused on a single topic">
    Documents that cover one topic thoroughly work better than large documents covering many topics. This helps the retrieval system find the most relevant chunks.
  </Accordion>

  <Accordion title="Use clear headings and structure">
    Well-structured documents with clear headings, bullet points, and short paragraphs produce better search results.
  </Accordion>

  <Accordion title="Update documents regularly">
    Keep your knowledge base current by replacing outdated documents. Stale information leads to inaccurate answers.
  </Accordion>

  <Accordion title="Test with real questions">
    After uploading documents, test your assistant with the kinds of questions your users will actually ask.
  </Accordion>

  <Accordion title="Scope each assistant to one audience">
    Knowledge belongs to the assistant, so give each audience its own assistant instead of pooling everything into one. Keep customer-facing product docs on your support assistant, and internal HR policy on a separate private assistant.
  </Accordion>
</AccordionGroup>

## Q\&A Pairs

Q\&A pairs let you curate precise answers for frequently asked questions. When a user's question closely matches a stored Q\&A pair, the assistant returns the curated answer directly -- providing more concise, accurate responses than general document retrieval.

### How Q\&A Matching Works

IllumiChat uses a hybrid matching strategy for Q\&A pairs:

1. **Direct match** -- Your question text is embedded and compared semantically against stored Q\&A pairs. If the similarity score meets the confidence threshold, the paired answer is returned verbatim.
2. **RAG fallback** -- If there is no high-confidence direct match, Q\&A content participates in standard document retrieval alongside your uploaded files, so partial or indirect matches can still surface.

This means Q\&A pairs give you the best of both worlds: precise answers for known questions and fuzzy relevance for everything else.

<Info>
  Q\&A pairs share the same document quota as your uploaded files. Each Q\&A pair counts as one knowledge document.
</Info>

### Adding Q\&A Pairs

<Steps>
  <Step title="Open your assistant's Knowledge Base">
    Open the assistant you want to teach, then go to its **Knowledge Base**.
  </Step>

  <Step title="Open the Q&A card">
    Under **Static knowledge**, click the **Q\&A Pairs** card. It sits alongside the Files, Websites, and Text cards.
  </Step>

  <Step title="Create a new pair">
    Click **Add Q\&A** and fill in the **Question** and **Answer** fields.
  </Step>

  <Step title="Save">
    Click **Save**. The Q\&A pair is synced automatically and available to this assistant.
  </Step>
</Steps>

### Managing Q\&A Pairs

From the Q\&A Pairs card, you can:

* **Edit** an existing pair to update the question or answer
* **Delete** pairs that are no longer needed
* **View all pairs** in a list with the question and a preview of the answer

<Tip>
  Start with Q\&A pairs for your top 10-20 most common support questions. These are the questions your team answers repeatedly -- giving your assistant curated answers for these dramatically improves response quality.
</Tip>

### When to Use Q\&A vs. Documents

| Use Case                                             | Recommended Approach                                                                  |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
| A specific question with a precise answer            | **Q\&A pair** -- The assistant returns the exact answer you wrote                     |
| Detailed product documentation or guides             | **Document upload** -- RAG retrieves relevant sections as needed                      |
| FAQ content you already have in a document           | **Both** -- Upload the document and create Q\&A pairs for the most critical questions |
| Policies or procedures with nuance                   | **Document upload** -- Lets the assistant draw from the full context                  |
| Quick factual answers (hours, pricing, contact info) | **Q\&A pair** -- Ensures accuracy for simple lookups                                  |

### Best Practices for Q\&A Pairs

<AccordionGroup>
  <Accordion title="Write questions the way your users ask them">
    Use natural, conversational phrasing. If your users ask "How do I reset my password?" rather than "Password reset procedure," write the question that way. The semantic matching works best when your stored question mirrors real user queries.
  </Accordion>

  <Accordion title="Keep answers concise and complete">
    Write answers that fully address the question without unnecessary detail. If the answer requires a longer explanation, consider linking to a document or guide.
  </Accordion>

  <Accordion title="Create variations for important questions">
    If a critical question can be asked in very different ways, consider adding separate Q\&A pairs for each variation to maximize match accuracy.
  </Accordion>

  <Accordion title="Review and update regularly">
    As your product or policies change, update your Q\&A pairs to stay current. Outdated answers erode user trust.
  </Accordion>
</AccordionGroup>

<Tip>
  For the best support bot experience, combine Q\&A pairs for your most common questions with uploaded FAQs, help center articles, and troubleshooting guides. This gives your assistant precise answers for known questions and broad knowledge for everything else.
</Tip>


# Facebook Messenger Integration
Source: https://docs.illumichat.com/features/messenger

Enable AI-powered Facebook Messenger conversations for your assistants

## What is Messenger Integration?

Messenger Integration lets your IllumiChat assistants respond to Facebook Messenger conversations automatically. When someone messages your Facebook Page, your assistant reads the message, generates a helpful response, and sends it back — all via Messenger.

Perfect for:

* **Customer support**: Let customers message your Facebook Page for instant AI-powered help
* **Lead engagement**: Capture and respond to inbound leads from Facebook 24/7
* **After-hours coverage**: Provide instant responses even when your team is offline
* **Human handoff**: Seamlessly transfer conversations to a human agent when needed

<Note>
  Messenger Integration connects via the **Meta Graph API** using OAuth. You'll authorize IllumiChat to manage messages on behalf of your Facebook Page.
</Note>

## Getting Started

### Prerequisites

Before setting up Messenger, you'll need:

1. An IllumiChat workspace with **Admin** access
2. A **Facebook Page** that you manage (you must be a Page admin)
3. A **Meta App** with Business Verification completed (for production use)
4. The Meta App must have the **Messenger** product added

<Tip>
  For testing, you can use a Meta App in Development Mode. Messages will only work with users who have a role on the app (admin, developer, tester). Complete Business Verification and App Review to message anyone.
</Tip>

### 1. Connect Your Facebook Page

1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **Messenger** card
4. Click **Connect with Facebook**
5. Log in to Facebook and authorize the required permissions
6. Select the Facebook Page you want to connect
7. Click **Connect**

IllumiChat will:

* Verify your Page Access Token and messaging permissions
* Subscribe the Page to Messenger webhook events (messages, postbacks, delivery receipts, read receipts)
* Encrypt and store your Page Access Token securely

<Warning>
  Each Facebook Page can only be connected to **one** assistant at a time. If the Page is already connected to another assistant, you'll need to disconnect it first.
</Warning>

### 2. Configure Settings

After connecting, configure your Messenger settings:

| Option                   | Default | Description                                      |
| ------------------------ | ------- | ------------------------------------------------ |
| **Enabled**              | On      | Toggle Messenger on or off without disconnecting |
| **Max Message Length**   | 2000    | Maximum characters per response (50-2000)        |
| **Contact Matching**     | Off     | Match Messenger users to existing contacts       |
| **Auto-Create Contacts** | Off     | Create contacts for new Messenger conversations  |

### 3. Configure Messenger Profile

Customize how your Facebook Page appears in Messenger:

| Setting                | Limit                     | Description                                                                                                                 |
| ---------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Greeting Text**      | 160 characters            | Message shown when someone opens a new conversation with your Page (before any messages are sent)                           |
| **Get Started Button** | 1000 characters (payload) | A "Get Started" button that appears in new conversations. When tapped, it triggers your assistant to send a welcome message |

<Tip>
  A good greeting text sets expectations. Example: "Hi! I'm the AI assistant for Acme Co. Tap Get Started to chat with me about our products and services."
</Tip>

### 4. Test It Out

Send a message to your connected Facebook Page via Messenger. Within a few seconds, you should receive an AI-generated response.

<Note>
  If your Meta App is in **Development Mode**, only users with a role on the app can message your Page and receive responses. Add testers in the Meta App Dashboard under **App Roles**.
</Note>

## How It Works

When someone sends a Messenger message to your Facebook Page:

1. **Meta receives the message** and forwards it to IllumiChat via webhook
2. **IllumiChat validates** the request using the X-Hub-Signature-256 header
3. **A conversation session** is created (or resumed) for that user using their Page-Scoped User ID (PSID)
4. **A typing indicator** is shown to the user while your assistant generates a response
5. **Your assistant generates a response** using its system prompt with Messenger-specific guidelines
6. **The response is formatted** — markdown is stripped and the message is kept under 2000 characters
7. **The response is sent back** via the Meta Send API
8. **The full conversation** is saved to your chat history for review

Your assistant automatically adapts to Messenger by keeping responses conversational, using short paragraphs (chat bubbles), and including emojis where appropriate.

### Message Handling

Messenger has a **2000 character limit** per message. If your assistant generates a longer response:

* Markdown formatting is automatically stripped (headers, bold, code blocks, links)
* The message is split at paragraph boundaries, then sentence boundaries, then word boundaries
* Each chunk is sent as a separate Messenger message to maintain readability
* Line breaks and emojis are preserved

### Messaging Windows

Messenger enforces a **24-hour messaging window**. Your assistant can only send automated responses within 24 hours of the user's last message. After that window expires:

* **AI responses**: Cannot be sent until the user sends a new message
* **Human Agent messages**: Can be sent for up to **7 days** using the Human Agent message tag (requires Meta approval)

### Get Started Button

When configured, a "Get Started" button appears at the bottom of new Messenger conversations. When a user taps it:

1. A postback event is sent to IllumiChat
2. A new conversation session is created
3. Your assistant generates and sends a welcome response

This is a great way to onboard new users and set the tone for the conversation.

### Attachments

Currently, IllumiChat processes **text messages only**. If a user sends an image, video, or other attachment, the assistant responds with a message explaining that it can only handle text at this time.

## Human Takeover

Sometimes a conversation needs a human touch. Messenger Integration includes a full human takeover system that lets your team step in, respond directly, and hand back to AI when ready.

### Activating Takeover

1. Go to your assistant's **Channels > Messenger** page
2. Open the **Conversations** list
3. Find the conversation you want to take over
4. Click **Take Over**
5. Optionally set an **auto-resume timer** (5 minutes to 7 days)

When takeover is active:

* AI stops responding to that conversation
* The conversation shows a **Human** badge
* Admins can send messages directly to the user

### Sending Messages as a Human

While in takeover mode, use the send message interface to type and send messages directly to the Messenger user. Messages are sent through the Meta Send API just like AI responses.

If the 24-hour standard messaging window has expired, messages are automatically sent using the **HUMAN\_AGENT** message tag, which extends the window to 7 days.

### Resuming AI

To hand the conversation back to AI:

1. Click **Resume AI** on the conversation
2. AI immediately starts responding to new messages from that user

### Auto-Resume

When activating takeover, you can set an auto-resume timer. After the specified duration, AI automatically resumes for that conversation. This prevents conversations from staying in human mode indefinitely if an agent forgets to hand back.

Timer options range from **5 minutes** to **7 days** (10,080 minutes).

## Messenger Analytics

Track how your Messenger integration is performing from the **Analytics** dashboard.

### Usage Metrics

* **Total Messages**: Combined inbound and outbound message counts
* **Inbound Messages**: Messages received from users
* **Outbound Messages**: Messages sent by your assistant or human agents
* **Delivered Messages**: Messages confirmed as delivered by Meta
* **Read Messages**: Messages confirmed as read by the recipient
* **Delivery Rate**: Percentage of outbound messages successfully delivered
* **Read Rate**: Percentage of outbound messages read by recipients

### Conversation Metrics

* **Total Conversations**: All Messenger conversations (across all time)
* **Active Conversations**: Conversations with messages in the selected period
* **Human Takeover Count**: Conversations currently in human takeover mode

### Daily Breakdown

View message volume by day to identify trends and peak usage periods. The chart shows inbound vs outbound messages over time.

Access analytics from your assistant's **Channels > Messenger** detail page. Filter by time period: **7 days**, **30 days**, or **90 days**.

## Conversations

Browse Messenger conversations from the **Conversations** section on the Messenger channel page. Each conversation shows:

* User name and profile picture (fetched from Facebook)
* **AI** or **Human** badge (whether AI is actively responding)
* Message count and last activity time
* Messaging window expiry (whether you can still send messages)
* Auto-resume time (if takeover is active with a timer)

## Admin Configuration

All Messenger management requires **Admin** role in the workspace. Admins can:

* Connect and disconnect Facebook Pages
* Enable/disable the Messenger channel
* Update settings (max message length, contact matching, greeting text)
* View analytics and conversation history
* Activate and manage human takeover
* Send messages as a human agent

## AI control

You can turn off AI replies for Messenger without disconnecting the channel: in the Messenger settings, toggle **"AI replies to Messenger messages"** off. Conversations still arrive in the [Universal Inbox](/features/inbox) — your team just handles them manually instead of the AI. This channel-level switch combines with the per-conversation **Pause AI** control in the inbox: if either says off, the AI stays quiet. See the [Universal Inbox guide](/features/inbox#ai-control) for details.

## Best Practices

<AccordionGroup>
  <Accordion title="Customize your assistant's prompt for Messenger">
    Add Messenger-specific instructions to your assistant's system prompt. For example: "Keep responses conversational and friendly. Use short paragraphs since Messenger displays messages in chat bubbles. Emojis are welcome."
  </Accordion>

  <Accordion title="Set up a greeting text and Get Started button">
    A greeting text tells users what to expect before they start chatting. The Get Started button provides a clear entry point and triggers your assistant's welcome message.
  </Accordion>

  <Accordion title="Use human takeover for complex issues">
    When a conversation requires human judgment — complaints, sensitive topics, or complex support cases — activate takeover. Set an auto-resume timer so conversations don't get stuck in human mode.
  </Accordion>

  <Accordion title="Keep responses concise">
    Messenger users expect quick, conversational replies. Aim for responses under 1000 characters when possible. Longer responses are automatically split into multiple messages.
  </Accordion>

  <Accordion title="Monitor analytics regularly">
    Check your delivery rate and read rate. A low delivery rate may indicate token issues. A low read rate might mean your responses need to be more engaging or timely.
  </Accordion>

  <Accordion title="Complete Meta App Review for production">
    In development mode, only app role holders can interact with your bot. Submit your Meta App for review to enable messaging with all users. You'll need to demonstrate a clear use case and comply with Meta's platform policies.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### No Facebook Pages found during setup

* Ensure the Facebook user authorizing the connection is an **admin** of the Page
* The Page must exist and be published (unpublished Pages may not appear)
* If re-authorizing, make sure to grant **all** requested permissions (especially `pages_messaging` and `pages_manage_metadata`)
* The setup screen will display a diagnostic hint explaining why no Pages were found

### Not receiving messages

* Verify the Messenger channel is **enabled** in your configuration
* Check that the connection status shows **Active** on the config page
* Ensure your Meta App has the **Messenger** product configured
* In development mode, the sender must have a role on the Meta App

### Token expired or revoked

Page Access Tokens can expire if the underlying user token is revoked or the app permissions are removed. If you see a connection status of "Expired" or "Revoked":

1. Go to your assistant's **Channels > Messenger** page
2. Click **Reconnect** to re-authorize with Facebook
3. Your existing configuration, settings, and conversation history are preserved

### Messages not delivering

* Check the **Analytics** dashboard for failed message counts
* Ensure the conversation is within the **24-hour messaging window** (or use human takeover with the HUMAN\_AGENT tag)
* Verify your Meta App has completed **App Review** for production messaging
* Check the [Meta Platform Status](https://metastatus.com/) for outages

### Get Started button not appearing

* The Get Started button may take a few minutes to propagate after configuration
* Verify you've set a **Get Started payload** in the Messenger settings
* The button only appears in **new** conversations — existing threads won't show it
* Clear your Messenger conversation history to test with a fresh thread

### Meta App Review issues

To send messages to users outside your development team, your Meta App needs approval:

* Submit for review with the `pages_messaging` permission
* Provide a clear description of your bot's purpose
* Include a screencast showing how the bot responds to messages
* Ensure your bot complies with [Meta's Platform Policies](https://developers.facebook.com/docs/messenger-platform/policy/)

<Warning>
  Messenger has a **24-hour standard messaging window**. Your assistant can only send automated messages to users who have messaged you within the last 24 hours. After that, you'll need the user to send a new message to reopen the window. Human agents can use the HUMAN\_AGENT tag to extend this to 7 days.
</Warning>

<Card title="Need help?" icon="envelope" href="mailto:support@illumichat.com">
  Contact support for Messenger setup assistance
</Card>


# Shopify Integration
Source: https://docs.illumichat.com/features/shopify

Connect your Shopify store and turn your assistant into an AI-powered e-commerce agent

Connect your Shopify store to IllumiChat and transform your AI assistant into an e-commerce agent that helps customers browse products, track orders, manage carts, and update their account — all through natural conversation.

<Note>
  **You do not need to edit your theme's code.** IllumiChat's chat widget is delivered as a Shopify **theme app embed** — after you connect your store, you turn it on with a single toggle in your theme editor. The **Enable in theme editor** button in IllumiChat links you straight to it.
</Note>

## What Your Customers Can Do

Once connected, your assistant can handle real shopping conversations:

<CardGroup>
  <Card title="Browse Products" icon="magnifying-glass">
    "Do you have any running shoes under \$100?"

    Your assistant searches your Shopify catalog and returns real products with names, prices, images, and links.
  </Card>

  <Card title="Track Orders" icon="truck">
    "Where's my order #1042?"

    Customers can check order status by order number or the email address they used at checkout.
  </Card>

  <Card title="Manage Carts" icon="cart-shopping">
    "Add the blue hoodie in size M to my cart"

    Your assistant can create a cart, add or remove items, and share a checkout link.
  </Card>

  <Card title="Update Account Info" icon="user">
    "Can you update my shipping address?"

    Look up customer records and update contact details, addresses, and notes.
  </Card>
</CardGroup>

## Getting Started

### Prerequisites

* An IllumiChat workspace with **Admin** access
* A [Shopify store](https://www.shopify.com) (development stores work for testing)
* Your store's `.myshopify.com` domain

### Quick Setup (Recommended)

The fastest way to get started is through the assistant creation wizard:

1. Click **New Assistant** and check **Shopify Store** in the assistant type step
2. Configure your assistant's name and system prompt
3. Add your store URL in the Knowledge step — your store will be auto-crawled for product pages, FAQs, and policies
4. In the Share step, enter your `.myshopify.com` domain and click **Connect to Shopify**
5. Approve permissions in Shopify — you'll be redirected back automatically
6. **Turn on the widget:** click **Enable in theme editor**, toggle **IllumiChat Widget** on in the **App embeds** tab, and click **Save**

That's it — your assistant is live on your storefront.

<Tip>
  You can enter just your store name (e.g., `my-store`) without the `.myshopify.com` part — IllumiChat adds it automatically.
</Tip>

<Warning>
  **Use your `.myshopify.com` domain, not your custom domain.** If your store has a custom domain like `petfood.shop`, that won't work here — IllumiChat needs the underlying `.myshopify.com` address (e.g., `petfood-store.myshopify.com`). To find it, go to your Shopify admin dashboard: **Settings > Domains**. Your `.myshopify.com` domain is listed there as your default Shopify domain.
</Warning>

<Note>
  **Product Search** and **Order Tracking** are enabled by default. To toggle **Cart Management** or **Customer Updates**, go to your assistant's **Knowledge Base → Realtime data → Shopify** after setup.
</Note>

### Manual Setup

If you already have an assistant and want to add Shopify:

1. Go to your assistant's **Knowledge Base → Realtime data → Shopify**
2. Enter your store domain and click **Connect**
3. Approve permissions in Shopify
4. Enable the AI actions you want:

| Action               | Default | What It Does                                                                 |
| -------------------- | ------- | ---------------------------------------------------------------------------- |
| **Product Search**   | On      | Search your catalog by keyword, return product details with prices and links |
| **Order Tracking**   | On      | Look up order status by order number or customer email                       |
| **Cart Management**  | Off     | Create shopping carts, add/remove items, share checkout links                |
| **Customer Updates** | Off     | Look up and update customer information (address, email, notes)              |

5. **Turn on the widget:** in the **Enable the widget on your storefront** card, click **Enable in theme editor**, toggle **IllumiChat Widget** on, and click **Save**

<Tip>
  Start with **Product Search** and **Order Tracking** — these cover the most common customer questions. Add Cart Management and Customer Updates when you need them.
</Tip>

### Turning on the widget

IllumiChat's widget is a Shopify **theme app embed** — there's no code to paste and nothing to "install." You turn it on once per theme:

1. From your assistant's **Knowledge Base → Realtime data → Shopify**, click **Enable in theme editor** (this deep-links you straight to the right screen), or in Shopify admin go to **Online Store → Themes → Customize → App embeds**.
2. Toggle **IllumiChat Widget** on.
3. Click **Save**.

<Warning>
  App embeds are **per-theme**. If you switch or duplicate your live theme, re-enable **IllumiChat Widget** on the new theme (**Online Store → Themes → Customize → App embeds**).
</Warning>

### Test the Connection

Click **Test Connection** on the Shopify settings page to verify everything is working. Then visit your storefront and try asking the widget about your products.

## Shopify Actions

Shopify Actions are the AI-powered capabilities your assistant uses to interact with your store data in real time. Each action can be toggled on or off independently.

### Product Search

When enabled, your assistant can search your entire Shopify product catalog and return real results including:

* Product name and description
* Price and variants (sizes, colors)
* Product images
* Direct links to the product page

**Example conversations:**

* "What laptops do you have?"
* "Show me dresses under \$50"
* "Do you have the Nike Air Max in size 10?"

### Order Tracking

Your assistant can look up any order using either the order number or the customer's email address. It returns:

* Current order status (fulfilled, unfulfilled, partially fulfilled)
* Tracking information
* Line items and quantities
* Order total

**Example conversations:**

* "Where's my order #1042?"
* "Can you check the status of my recent order? My email is [jane@example.com](mailto:jane@example.com)"

### Cart Management

Your assistant can create shopping carts and manage items during the conversation:

* Create a new cart
* Add products by name or variant
* Remove items
* Show cart summary with totals

**Example conversations:**

* "Add the blue hoodie in medium to my cart"
* "What's in my cart?"
* "Remove the socks from my cart"

### Customer Updates

Your assistant can look up and modify customer records:

* Find customers by email
* Update shipping/billing addresses
* Update contact information
* Add notes to customer profiles

**Example conversations:**

* "Update my address to 123 Main St, New York, NY 10001"
* "What email do you have on file for me?"

<Note>
  Customer Updates requires the `read_customers` scope. This is included by default when you connect your store.
</Note>

## Analytics

Track how customers are using your Shopify integration from the analytics dashboard on your assistant's **Knowledge Base → Realtime data → Shopify** page.

**Metrics tracked:**

* **Product Searches** — How often the assistant searches your catalog
* **Order Lookups** — Number of order status inquiries
* **Cart Actions** — Cart creates, item additions, and removals
* **Customer Updates** — Customer data lookups and modifications
* **Webhooks Received** — Store events received from Shopify

Filter by **7 days**, **30 days**, or **90 days** to spot trends.

## Managing Your Integration

### Enable / Disable

Toggle the integration on or off from the Shopify page without losing your configuration. When disabled, AI actions stop and the widget stops responding, but your store stays connected.

### Disconnect Store

Click **Disconnect Store** to remove the integration and delete the stored access token. The chat widget stops working immediately. To also remove the app embed from your theme, toggle **IllumiChat Widget** off in **Online Store → Themes → Customize → App embeds**. You can reconnect at any time by going through the OAuth flow again.

### Connection Status

Your assistant's **Knowledge Base → Realtime data** page shows the Shopify connection status at a glance:

* **Connected** (green) — Store is connected and active
* **Not Connected** — No store linked yet

## Best Practices

<AccordionGroup>
  <Accordion title="Your store is automatically crawled for knowledge">
    When you connect via the wizard, your Shopify store is automatically crawled to build a knowledge base — including product pages, FAQs, and policies. This usually takes about 30 seconds. You can review and manage crawled content from the **Knowledge** tab in your assistant's settings.
  </Accordion>

  <Accordion title="Customize your assistant's prompt for e-commerce">
    Add Shopify-specific instructions to your assistant's system prompt. For example:

    *"When helping with product questions, always include the price and a link to the product page. If a product is out of stock, suggest similar alternatives. Keep responses concise and helpful."*
  </Accordion>

  <Accordion title="Test with a development store first">
    Shopify offers free [development stores](https://help.shopify.com/en/partners/dashboard/managing-stores/development-stores) for testing. Connect one first to verify your assistant handles product searches and order lookups correctly before going live.
  </Accordion>

  <Accordion title="Only enable the actions you need">
    Fewer tools means faster, more focused responses. Most stores only need Product Search and Order Tracking. Add Cart Management and Customer Updates when you have specific use cases for them.
  </Accordion>

  <Accordion title="Monitor analytics to improve your store">
    High product search volume suggests customers need better product discovery on your site. High order lookups may indicate gaps in your shipping notifications. Use the data to improve both your assistant and your store.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth connection fails">
    * Verify your store domain is correct (must be a valid `.myshopify.com` domain)
    * Ensure you have owner or admin access on the Shopify store
    * Make sure your IllumiChat instance is accessible via HTTPS
  </Accordion>

  <Accordion title="Widget not appearing on storefront">
    * Confirm **IllumiChat Widget** is toggled on in your **active** (live) theme's **App embeds** tab — not an unpublished draft
    * If you recently switched themes, re-enable the app embed on the new theme (app embeds are per-theme)
    * Clear your browser cache or try an incognito window
    * Make sure the integration is **enabled** (not just connected)
  </Accordion>

  <Accordion title="AI actions not working">
    * Verify the store is connected (green status on the **Knowledge Base → Realtime data** page)
    * Ensure the specific action toggle is **on** (e.g., Product Search)
    * Click **Test Connection** to verify the access token is still valid
    * If the test fails, disconnect and reconnect the store
  </Accordion>

  <Accordion title="Store disconnected unexpectedly">
    * The store owner may have uninstalled the app from Shopify's admin
    * The access token may have been revoked
    * Reconnect from **Knowledge Base → Realtime data → Shopify** — it only takes a few clicks
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Widget Customization" icon="paintbrush" href="/guides/widget-customization">
    Customize the look and feel of the chat widget on your storefront.
  </Card>

  <Card title="Effective Prompts" icon="wand-magic-sparkles" href="/guides/effective-prompts">
    Write better system prompts to get the most out of your Shopify assistant.
  </Card>
</CardGroup>


# SMS Integration
Source: https://docs.illumichat.com/features/sms

Enable AI-powered text messaging for your assistants with Twilio

## What is SMS Integration?

SMS Integration lets your IllumiChat assistants respond to text messages automatically. When someone texts your Twilio phone number, your assistant reads the message, generates a helpful response, and sends it back — all via SMS.

Perfect for:

* **Customer support**: Let customers text in for instant AI-powered help
* **Appointment reminders**: Respond to scheduling questions automatically
* **Lead engagement**: Capture and respond to inbound leads 24/7
* **Internal helpdesks**: Give employees quick answers via text

<Note>
  SMS Integration uses **Bring Your Own Key (BYOK)** — you connect your own Twilio account. Message and phone number costs are billed directly by Twilio.
</Note>

## Getting Started

### Prerequisites

Before setting up SMS, you'll need:

1. An IllumiChat workspace with **Admin** access
2. A [Twilio account](https://www.twilio.com/try-twilio) (free trial works for testing)
3. A Twilio phone number with SMS capability
4. Your Twilio **Account SID** and **Auth Token**

### 1. Find Your Twilio Credentials

1. Log in to [console.twilio.com](https://console.twilio.com)
2. Your **Account SID** and **Auth Token** are on the dashboard homepage
3. Note your Twilio phone number (e.g., +15551234567)

<Tip>
  Your Account SID starts with `AC` followed by 32 characters. Keep your Auth Token secret — treat it like a password.
</Tip>

### 2. Configure SMS in IllumiChat

1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **SMS** card to open the SMS detail page
4. Enter your Twilio credentials:
   * **Account SID**: Your Twilio Account SID (starts with `AC`)
   * **Auth Token**: Your Twilio Auth Token
   * **Phone Number**: Your Twilio number in E.164 format (e.g., `+15551234567`)
5. Click **Test Credentials** to verify the connection
6. Configure optional settings (see below)
7. Click **Save**

### 3. Set Up Twilio Webhooks

After saving your SMS configuration, IllumiChat provides webhook URLs that you need to add to Twilio:

1. On the SMS detail page, find the **Webhook Setup** section
2. Go to [Twilio Console](https://console.twilio.com) → **Phone Numbers** → **Manage** → **Active Numbers**
3. Click your phone number
4. In the **Messaging** section:
   * Set **"A MESSAGE COMES IN"** to your **Inbound Webhook URL**
   * Select **HTTP POST**
5. Click **Save Configuration**

<Warning>
  Your IllumiChat instance must be accessible via HTTPS for Twilio webhooks to work. Webhooks will not work with localhost during local development.
</Warning>

### 4. Test It Out

Send a text message to your Twilio phone number. Within a few seconds, you should receive an AI-generated response from your assistant.

## Configuration Options

| Option                   | Default | Description                                                               |
| ------------------------ | ------- | ------------------------------------------------------------------------- |
| **Enabled**              | On      | Toggle SMS on or off without deleting your configuration                  |
| **Max Message Length**   | 1600    | Maximum characters per response (50-1600). Longer responses are truncated |
| **Contact Matching**     | Off     | Automatically match incoming phone numbers to existing contacts           |
| **Auto-Create Contacts** | Off     | Create a new contact when an unknown number texts in                      |

<Tip>
  SMS messages over 160 characters are split into multiple segments. Keeping responses concise helps reduce Twilio costs. The 1600 character limit allows up to \~10 SMS segments per response.
</Tip>

## How It Works

When someone sends a text to your Twilio number:

1. **Twilio receives the message** and forwards it to IllumiChat via webhook
2. **IllumiChat validates** the request using Twilio's signature verification
3. **A conversation session** is created (or resumed) for that phone number
4. **Your assistant generates a response** using its system prompt with SMS-specific guidelines
5. **The response is sent back** via Twilio as a text message
6. **The full conversation** is saved to your chat history for review

Your assistant automatically adapts to SMS by keeping responses concise and using plain text only — no markdown, code blocks, or complex formatting.

## SMS Analytics

Track how your SMS integration is performing from the **SMS Analytics** dashboard.

### Usage Metrics

* **Total Messages**: Inbound and outbound message counts
* **Segments Sent**: Total SMS segments (affects Twilio billing)
* **Delivery Rate**: Percentage of messages successfully delivered
* **Estimated Cost**: Approximate Twilio messaging cost

### Session Metrics

* **Total Sessions**: Unique phone numbers that have texted in
* **Active Sessions**: Currently active conversations
* **Contacts Matched**: Sessions linked to existing contacts

### Daily Breakdown

View message volume by day to identify trends and peak usage periods.

Access analytics from your assistant's **Channels → SMS** detail page. The analytics dashboard appears below the configuration form. Filter by time period: **7 days**, **30 days**, or **90 days**.

## SMS Sessions

Each unique phone number that texts your assistant creates a **session**. Sessions track:

* The phone number and conversation history
* Message count and timestamps
* Linked contact (if contact matching is enabled)
* Associated chat (viewable in your normal chat history)

Browse active sessions from the SMS detail page under **Channels → SMS** in your assistant settings.

## Contact Matching

When enabled, IllumiChat checks incoming phone numbers against your workspace contacts:

* **Contact Matching**: Links SMS sessions to existing contacts that share the same phone number
* **Auto-Create Contacts**: Automatically creates a new contact when an unrecognized number texts in

This helps you track which customers are reaching out via SMS and keeps conversations organized alongside your other contact interactions.

## Best Practices

<AccordionGroup>
  <Accordion title="Customize your assistant's prompt for SMS">
    Add SMS-specific instructions to your assistant's system prompt. For example: "When responding to customers, include a brief greeting and sign off with our company name."
  </Accordion>

  <Accordion title="Keep the max message length reasonable">
    While you can set up to 1600 characters, shorter responses (under 320 characters / 2 segments) are more natural for SMS and cost less.
  </Accordion>

  <Accordion title="Test with your own phone first">
    Before sharing your SMS number publicly, text it yourself to make sure the responses are accurate and appropriately formatted.
  </Accordion>

  <Accordion title="Monitor analytics regularly">
    Check your delivery rate and failed messages. A low delivery rate may indicate phone number issues or carrier filtering.
  </Accordion>

  <Accordion title="Use contact matching for returning customers">
    Enable contact matching to build a history of interactions. This makes it easier to follow up and provide context-aware support.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Not receiving responses

* Verify your Twilio credentials are correct using **Test Credentials**
* Check that SMS is **enabled** in your configuration
* Confirm webhook URLs are correctly set in the Twilio console
* Ensure your Twilio account has sufficient balance
* Check that the phone number has SMS capability

### Messages failing to deliver

* Check the **SMS Analytics** for error details
* Verify the recipient's phone number is valid
* Ensure your Twilio number is not flagged or suspended
* Check Twilio's [status page](https://status.twilio.com) for outages

### Delayed responses

* AI response generation typically takes 2-5 seconds
* Twilio delivery adds 1-3 seconds
* Long system prompts or complex queries may take longer

### Webhook errors

* Ensure your app URL uses HTTPS
* Verify the webhook URL matches exactly (no trailing slashes)
* Check that Twilio signature validation is passing — the webhook secret must match

<Card title="Need help?" icon="envelope" href="mailto:support@illumichat.com">
  Contact support for SMS setup assistance
</Card>


# Sandbox
Source: https://docs.illumichat.com/features/testing

Try your assistant before it goes live — chat with it or batch-test its answers

Sandbox is the one place to try your assistant before you put it in front of customers. Open an assistant and go to the **Sandbox** tab. It has two views:

* **Chat** — talk to your assistant in the real chat widget, exactly as visitors will.
* **Batch tests** — build a set of questions, run them all at once, and see each answer graded, with the knowledge sources the assistant used.

Everything in Sandbox is free and never counts against your credits.

## Chat

The **Chat** tab embeds the real chat widget — the same surface your visitors use, so forms, theming, file upload, lead capture, and handoff all behave identically here. Because it is the live widget, what you see is exactly what customers get.

* **Reset** restarts the conversation so you can try again with a fresh session (handy after changing instructions or knowledge).
* **Open full screen** opens the same preview in a new browser tab.

<Tip>
  The Chat preview works even while an assistant is disabled or private, so you can try changes before publishing.
</Tip>

## Batch tests

The **Batch tests** tab lets you check how your assistant answers many real questions at once and see each answer graded.

### Building a question bank

Open the **Batch tests** tab. You can add questions three ways:

<Steps>
  <Step title="Add questions manually">
    Type a question a customer might ask and click **Add question**.
  </Step>

  <Step title="Generate from your knowledge base">
    Click **Generate from knowledge base** to create a starter set based on the content your assistant knows. This works even for a brand-new assistant.
  </Step>

  <Step title="Generate from past conversations">
    Click **Generate from past conversations** to turn real questions your customers have already asked into a test set. If the assistant has no history yet, use one of the other options.
  </Step>
</Steps>

## Running a test

Click **Run test** to send every question through your assistant. Runs happen in the background, so you can leave the page and come back. Each answer is graded automatically:

* **Good** — relevant, complete, and supported by your content.
* **Acceptable** — mostly right, but incomplete or lightly unsupported.
* **Poor** — off-topic, incorrect, or unsupported.

Each result also shows the knowledge sources the assistant used to answer, so you can see why it responded the way it did. A **Not grounded** flag means the answer made specific claims without a supporting source.

## Seeing the reasoning

Expand **Reasoning** on any result to see how the assistant arrived at its answer:

* **Tools fired** — which tools the assistant used and what it passed them. For a knowledge base search, this is the exact query it ran.
* **Q\&A match** — when the answer came straight from a Q\&A pair, the matched question and its confidence score.
* **Retrieved passages** — the knowledge-base chunks the assistant pulled in, each with its document name and relevance score, so you can judge whether it retrieved the right content.

If a result shows **"No tools were used — the model answered from its instructions alone,"** the assistant answered without consulting your knowledge base. That is expected for small talk, but for a factual question it is a signal to check the answer closely.

<Tip>
  You can see the same reasoning live while chatting in the **Chat** tab — expand **Why this answer** under any reply to see the query and passages behind it. This preview is only visible to you; visitors using the real widget never see it.
</Tip>

## Reviewing and overriding grades

You can override any automatic grade with your own judgment using the grade dropdown on each result. Use this to keep track of which answers you have reviewed and to record where the assistant needs better content or instructions.

<Tip>
  If an answer is graded Poor or Not grounded, add or improve the relevant knowledge in the **Knowledge Base** tab, then run the test again.
</Tip>


# Support Tickets
Source: https://docs.illumichat.com/features/tickets

Track and manage customer support requests

Support tickets let you track customer issues from creation through resolution. When a customer reaches out through the chat widget, sends a message, or when your team identifies an issue, a ticket captures the details and tracks progress.

## Ticket Lifecycle

Every ticket moves through a series of statuses:

| Status                  | Description                                      |
| ----------------------- | ------------------------------------------------ |
| **New**                 | Just created, awaiting review                    |
| **Open**                | Acknowledged by your team, work has not started  |
| **In Progress**         | Being actively worked on                         |
| **Waiting on Customer** | Your team has responded, awaiting customer reply |
| **Resolved**            | The issue has been fixed                         |
| **Closed**              | Ticket is complete, no further action needed     |
| **Spam**                | Marked as spam and excluded from active views    |

<Tip>
  Use **Waiting on Customer** to keep your active ticket count focused on issues that need your team's attention.
</Tip>

## Priority Levels

| Priority     | When to use                                           |
| ------------ | ----------------------------------------------------- |
| **Critical** | Service is down or a major feature is broken          |
| **High**     | Significant issue affecting the customer's workflow   |
| **Normal**   | Standard support request or question                  |
| **Low**      | Minor issue, enhancement request, or general feedback |

## Creating Tickets

### From the Dashboard

<Steps>
  <Step title="Open the tickets dashboard">
    Click **Tickets** in your workspace sidebar.
  </Step>

  <Step title="Create a new ticket">
    Click **New Ticket**.
  </Step>

  <Step title="Fill in the details">
    Enter a subject and description. Set the priority level and optionally assign it to a team member.
  </Step>

  <Step title="Link a contact">
    If the ticket relates to a specific customer, link their contact record.
  </Step>

  <Step title="Save the ticket">
    Click **Create**. It starts with a **New** status.
  </Step>
</Steps>

### From Widget Conversations

When a visitor uses the chat widget, tickets can be created from the conversation. This links the ticket to the conversation so your team has full context.

## Ticket Activities

Every ticket maintains an activity log that records its full history:

* Status changes (e.g., New to In Progress)
* Priority changes
* Assignments and reassignments
* Notes and internal comments from team members
* Links to related chat conversations

The activity log provides a complete audit trail.

### Chat Linking

You can link a chat conversation to a ticket, giving your team one-click access to the full conversation that led to the support request.

## Widget Ticket Creation

The chat widget can create tickets from visitor conversations.

<Steps>
  <Step title="Open the assistant's Forms page">
    Go to your assistant, open **Forms**, and switch to the **Support Tickets** tab.
  </Step>

  <Step title="Enable the form">
    Turn on **Enable Form**. This switches on ticket creation for the assistant and its widget in one step.
  </Step>

  <Step title="Choose what the ticket collects">
    Add and arrange the fields the visitor fills in -- subject, description, and anything else you need. A **Dropdown** field with **Save answer to** set to **Ticket issue type** makes the answer reportable instead of leaving it in the submission data. See [Forms](/widget/configuration#forms) for every field type and setting.
  </Step>

  <Step title="Set contact requirements">
    Optionally open workspace **Settings > Tickets** and enable **Require Contact Info** to require a name and email on tickets created from the widget.
  </Step>
</Steps>

<Note>
  When contact information is required, the widget prompts the visitor to enter their details before the ticket is submitted.
</Note>

## Access Control

| Role              | Capabilities                                                       |
| ----------------- | ------------------------------------------------------------------ |
| **Owner / Admin** | Create, edit, assign, close, delete, and configure ticket settings |
| **Member**        | Create, edit, and update tickets assigned to them                  |
| **Guest**         | View tickets only                                                  |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tickets are not being created from widget conversations">
    Verify that ticket creation is enabled in your assistant's widget settings. Check that the widget is using the correct assistant ID. If **Require contact info** is enabled, confirm the visitor completed the form.
  </Accordion>

  <Accordion title="Cannot find a ticket">
    Check the status filter on the tickets dashboard. Tickets with **Closed** or **Spam** status may be hidden by default. Use the search bar to find tickets by subject.
  </Accordion>
</AccordionGroup>


# WhatsApp Business Integration
Source: https://docs.illumichat.com/features/whatsapp

Enable AI-powered WhatsApp Business conversations for your assistants

## What is WhatsApp Business Integration?

WhatsApp Business Integration lets your IllumiChat assistants respond to WhatsApp messages automatically. When someone messages your WhatsApp Business number, your assistant reads the message, generates a helpful response, and sends it back — all over WhatsApp.

Perfect for:

* **Customer support**: Let customers message your business number for instant AI-powered help
* **Lead engagement**: Capture and respond to inbound leads on the channel they already use
* **After-hours coverage**: Provide instant responses even when your team is offline
* **Human handoff**: Hand any conversation to a human agent in the [Universal Inbox](/features/inbox) when needed

<Note>
  WhatsApp Business Integration connects through the **Meta WhatsApp Cloud API**. You can connect with one click using **Embedded Signup**, or paste your own credentials with **Advanced Setup**.
</Note>

## Getting Started

### Prerequisites

Before connecting WhatsApp, make sure you have:

1. An IllumiChat workspace with **Admin** access
2. A **Meta Business Account**
3. A **WhatsApp Business Account (WABA)**
4. A **registered phone number** for WhatsApp Business

<Warning>
  Each WhatsApp phone number can only be connected to **one** assistant at a time. If the number is already connected elsewhere, disconnect it there first.
</Warning>

### 1. Connect Your WhatsApp Business Number

1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **WhatsApp** card
4. Review the prerequisites checklist
5. Click **Connect with WhatsApp**
6. Complete the Meta popup — log in to Facebook, choose your WhatsApp Business Account and phone number, and authorize access

IllumiChat will exchange the authorization, discover your WABA and phone number, subscribe the account to webhooks, and store your access token encrypted.

<Tip>
  Embedded Signup is the recommended path — it handles token generation and webhook subscription for you. If you don't see the **Connect with WhatsApp** button, your workspace is in manual-only mode and you'll use Advanced Setup below.
</Tip>

### Advanced Setup (manual credentials)

If you manage your own Meta App, expand **Advanced Setup (manual credentials)** and provide:

| Field                        | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| **Phone Number ID**          | The Cloud API phone number ID for your WhatsApp Business number |
| **WABA ID**                  | Your WhatsApp Business Account ID                               |
| **System User Access Token** | A long-lived System User token with WhatsApp permissions        |
| **App Secret**               | Your Meta App secret (used to validate incoming webhooks)       |

Then click **Connect Manually**. IllumiChat validates the credentials against the Cloud API and stores them encrypted.

<Note>
  With a manual connection, IllumiChat verifies incoming webhooks using **your** App Secret, so each customer's own Meta App can deliver events to the same shared webhook URL.
</Note>

### 2. Configure Webhooks (manual connections)

Embedded Signup subscribes your account to webhooks automatically — there's nothing extra to do.

If you connected manually, configure the webhook in your **Meta App Dashboard** under the WhatsApp product:

1. On the WhatsApp channel page, copy the **Webhook URL** shown in the **Webhook Setup** card (it ends in `/api/channels/webhook/whatsapp`)
2. In your Meta App Dashboard, paste it as the WhatsApp **Callback URL**
3. Enter your **Verify Token** (this must match the `META_WEBHOOK_VERIFY_TOKEN` configured for your deployment)
4. Subscribe to the **messages** webhook field

<Tip>
  The webhook is shared across all WhatsApp connections — you don't need a unique URL per assistant. Incoming events are routed to the right assistant by phone number.
</Tip>

### 3. Configure Messaging Settings

After connecting, fine-tune how conversations are handled from the **Messaging Settings** card:

| Option                                         | Default | Description                                                                                                  |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| **AI replies to WhatsApp messages**            | On      | When off, the AI stops replying on WhatsApp, but conversations still appear in the inbox for manual handling |
| **Match WhatsApp users to existing contacts**  | Off     | Link incoming messages to contacts with matching phone numbers                                               |
| **Auto-create contacts for new conversations** | Off     | Create a contact record for new WhatsApp users (requires contact matching)                                   |
| **Max message length**                         | 4096    | Maximum characters per message — 1000, 2000, 3000, or 4096; longer responses are split                       |

Use the **Enabled** toggle at the top of the WhatsApp Integration card to turn the channel on or off without disconnecting. Click **Save Changes** when you're done.

<Tip>
  Use **Test** on the connection card at any time to confirm the connection is active and working.
</Tip>

### 4. Test It Out

Send a message to your connected WhatsApp Business number. Within a few seconds, you should receive an AI-generated response.

## How It Works

When someone sends a message to your WhatsApp Business number:

1. **Meta forwards the message** to IllumiChat via the Cloud API webhook
2. **IllumiChat validates** the request using the `X-Hub-Signature-256` header (against the platform App Secret for Embedded Signup, or your own App Secret for manual connections)
3. **A conversation session** is created (or resumed) for that user, keyed to their WhatsApp ID
4. **Your assistant generates a response** if AI is enabled for the channel and the conversation
5. **The response is sent back** via the Cloud API and saved to your chat history

### The 24-Hour Customer Service Window

WhatsApp enforces a strict **24-hour customer service window**. Your assistant (and human agents) can only send free-form messages within 24 hours of the customer's last message. After that window closes, free-form replies are rejected — the customer must message you again to reopen it, **or** you can re-engage using an approved **template message**.

<Warning>
  Unlike Messenger, WhatsApp does **not** offer a human-agent tag to extend the window. Outside 24 hours, a pre-approved template is the only way to message a customer.
</Warning>

### Message Templates

Templates are pre-written, Meta-approved messages used for business-initiated conversations and to re-engage customers after the 24-hour window closes. Manage them from the **Message Templates** card on the WhatsApp channel page:

* **View templates** — Each template shows its **status** (Approved, Pending, Rejected, etc.), **category**, and language
* **Create a template** — Click **Create Template**, then provide:
  * **Template Name** — lowercase letters, numbers, and underscores only (e.g. `order_confirmation`)
  * **Category** — **Utility**, **Marketing**, or **Authentication**
  * **Language** — English (US/UK), Spanish, French, or Portuguese (BR)
  * **Body Text** — up to 1024 characters
* **Delete a template** — Remove templates you no longer need

<Note>
  New templates are submitted to Meta for review and start as **Pending**. They can only be used once Meta marks them **Approved** — review usually takes a few minutes but can take longer.
</Note>

## Human Handoff

Human handoff for WhatsApp happens in the **[Universal Inbox](/features/inbox)** — there is no separate WhatsApp agent screen. Your WhatsApp conversations appear in the inbox alongside Messenger, Instagram, and Live Chat, so your team works every channel from one place.

From the inbox you can:

* **Take over AI** on a conversation so the assistant stops replying and you respond manually
* **Claim** a conversation so teammates know you're handling it
* **Reply** directly to the customer over WhatsApp
* **Resume AI** to hand the conversation back to your assistant
* Set an **auto-resume timer** (from 5 minutes up to 7 days) so conversations don't stay in human mode indefinitely

<Warning>
  Human replies are still bound by the **24-hour customer service window**. If the window has expired, agent messages from the inbox cannot be sent until the customer messages again. Use an approved template to re-engage outside the window.
</Warning>

For full details on claiming, internal notes, and AI control, see the [Universal Inbox guide](/features/inbox).

## WhatsApp Analytics

Track how your WhatsApp integration is performing from the **WhatsApp Analytics** dashboard on the channel page. Filter by **Last 7 days**, **Last 30 days**, or **Last 90 days**.

### Usage Metrics

* **Total Messages**: Combined inbound and outbound message counts
* **Inbound Messages**: Messages received from users
* **Outbound Messages**: Messages sent by your assistant or human agents
* **Delivered Messages**: Messages confirmed as delivered by Meta
* **Read Messages**: Messages confirmed as read by the recipient
* **Delivery Rate**: Percentage of outbound messages successfully delivered
* **Read Rate**: Percentage of outbound messages read by recipients

### Conversation Metrics

* **Total Conversations**: All WhatsApp conversations
* **Active Conversations**: Conversations with activity in the selected period
* **Human Takeover Count**: Conversations currently in human takeover mode

### Daily Breakdown

View message volume by day to spot trends and peak usage periods, with inbound versus outbound messages over time. The dashboard also lists recent conversations for quick access.

## Admin Configuration

All WhatsApp management requires the **Admin** role in the workspace. Admins can:

* Connect and disconnect WhatsApp Business numbers
* Enable/disable the WhatsApp channel and update messaging settings
* Create, view, and delete message templates
* View analytics and conversation history
* Take over conversations and send messages as a human agent from the inbox

## Best Practices

<AccordionGroup>
  <Accordion title="Use Embedded Signup when you can">
    The one-click flow generates tokens and subscribes webhooks for you, so there's no manual credential management. Reserve Advanced Setup for cases where you run your own Meta App.
  </Accordion>

  <Accordion title="Prepare templates before you need them">
    Because templates require Meta review, create your common re-engagement messages ahead of time so they're already Approved when the 24-hour window closes on an active conversation.
  </Accordion>

  <Accordion title="Choose the right template category">
    Use **Utility** for transactional messages (order updates, reminders), **Marketing** for promotions, and **Authentication** for one-time passcodes. Picking the wrong category is a common cause of rejection.
  </Accordion>

  <Accordion title="Customize your assistant's prompt for WhatsApp">
    Add WhatsApp-specific guidance to your assistant's system prompt, such as keeping replies concise and conversational, since WhatsApp is a fast, chat-style channel.
  </Accordion>

  <Accordion title="Watch your quality rating">
    The connection card shows your number's quality rating (Green/Yellow/Red). A declining rating can lead to messaging limits — keep responses helpful and avoid spammy template sends.
  </Accordion>

  <Accordion title="Monitor analytics regularly">
    A low delivery rate may indicate token or quality issues; a low read rate may mean your responses need to be timelier or more engaging.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Connection failed or shows a connection issue

* Confirm your Meta Business Account, WhatsApp Business Account, and phone number are all set up and the number is registered for WhatsApp Business
* For manual connections, double-check the **Phone Number ID**, **WABA ID**, **System User Access Token**, and **App Secret** — an invalid or expired token is the most common cause
* If the connection card shows a **Connection issue**, **Disconnect** and reconnect to re-authorize
* Use the **Test** button to re-check that the connection is active

### Phone number already connected

Each WhatsApp number can only be connected to one assistant. Disconnect it from the other assistant before connecting it here.

### Not receiving messages

* Verify the WhatsApp channel is **Enabled** and the connection status is active
* For manual connections, confirm the **Webhook URL** is set in your Meta App Dashboard with the correct **Verify Token**, and that the **messages** field is subscribed
* Ensure the phone number is properly registered on the Cloud API

### Can't send a message — window expired

If you see an error that the messaging window has expired, more than 24 hours have passed since the customer's last message. WhatsApp does not allow free-form replies after this window. Wait for the customer to message again, or re-engage with an approved template.

### Template rejected or stuck pending

* Templates must be **Approved** by Meta before use; freshly created templates start as **Pending**
* A **Rejected** status usually means the content or category violates WhatsApp's policies — review Meta's feedback, fix the body text or category, and recreate it
* Template names must use lowercase letters, numbers, and underscores only

<Card title="Need help?" icon="envelope" href="mailto:support@illumichat.com">
  Contact support for WhatsApp setup assistance
</Card>


# WooCommerce Integration
Source: https://docs.illumichat.com/features/woocommerce

Connect your WooCommerce store and turn your assistant into an AI-powered e-commerce agent

Connect your WooCommerce store to IllumiChat and transform your AI assistant into an e-commerce agent that helps customers browse products, track orders, manage carts, and update their account — all through natural conversation.

<Note>
  **No manual coding required.** Install the free IllumiChat WordPress plugin and the chat widget appears on your storefront automatically.
</Note>

## What Your Customers Can Do

Once connected, your assistant can handle real shopping conversations:

<CardGroup>
  <Card title="Browse Products" icon="magnifying-glass">
    "Do you have any running shoes under \$100?"

    Your assistant searches your WooCommerce catalog and returns real products with names, prices, and links.
  </Card>

  <Card title="Track Orders" icon="truck">
    "Where's my order #1042?"

    Customers can check order status by order number or the email address they used at checkout.
  </Card>

  <Card title="Manage Carts" icon="cart-shopping">
    "Add the blue hoodie in size M to my cart"

    Your assistant can create a cart, add or remove items, and share a checkout link.
  </Card>

  <Card title="Update Account Info" icon="user">
    "Can you update my shipping address?"

    Look up customer records and update contact details and addresses.
  </Card>
</CardGroup>

## Prerequisites

* An IllumiChat workspace with **Admin** access
* A WooCommerce store (WordPress self-hosted or managed)
* **WooCommerce 7.0+** and **WordPress 6.0+**
* WordPress admin access

***

## Setup: Two Paths

There are two ways to connect, depending on where you start. Both end up in the same place.

### Path A — Start from IllumiChat (Recommended)

Use this if you're creating a new assistant or connecting via the Channels settings page.

#### Step 1: Connect your store

<Tabs>
  <Tab title="New assistant (wizard)">
    1. Click **New Assistant** and choose **WooCommerce** as your platform in the type step
    2. Configure your assistant's name and system prompt
    3. In the Share step, enter your full store URL — e.g. `https://yourstore.com` — and click **Connect Store**
  </Tab>

  <Tab title="Existing assistant">
    1. Open your assistant's **Settings → Channels → WooCommerce**
    2. Enter your full store URL and click **Connect**
  </Tab>
</Tabs>

IllumiChat redirects your browser to a WooCommerce consent screen:

> *"Would you like to grant \[IllumiChat] read\_write access to your store?"*

Click **Approve**. WooCommerce sends your store credentials directly to IllumiChat's server — you never handle API keys. You'll be redirected back to IllumiChat automatically.

#### Step 2: Download and install the WordPress plugin

The WordPress plugin is what puts the chat widget on your storefront.

1. After connecting, IllumiChat shows a **Download Plugin** button — click it to download `illumichat-wordpress.zip`
2. In your **WordPress admin**, go to **Plugins → Add New Plugin → Upload Plugin**
3. Click **Choose File**, select the downloaded `.zip`, and click **Install Now**
4. Click **Activate Plugin**

<Warning>
  **Critical: flush your permalink cache after activating.**
  Go to **Settings → Permalinks** in WordPress and click **Save Changes** — without changing anything. WordPress must register the plugin's REST API endpoint before IllumiChat can call it. Skipping this step causes a "Plugin endpoint returned 404" error.
</Warning>

#### Step 3: Push the widget to your storefront

Back in IllumiChat, click **Install widget via plugin**.

IllumiChat calls your store's plugin endpoint, which stores your assistant ID and enables the widget. The chat widget will now appear on every page of your storefront.

That's it. Your assistant is live.

***

### Path B — Start from WordPress (Plugin-first)

Use this if you've already installed the plugin and want to connect from within WordPress.

#### Step 1: Install and activate the plugin

Download `illumichat-wordpress.zip` from your IllumiChat dashboard or the channels page. Then:

1. In **WordPress admin → Plugins → Add New Plugin → Upload Plugin**, upload the zip and activate it
2. Go to **Settings → Permalinks** and click **Save Changes** (required to register the plugin's REST API endpoint)

#### Step 2: Configure the plugin

Go to **WooCommerce → IllumiChat** in your WordPress admin.

You'll see a settings form with:

| Field              | What to enter                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------- |
| **Assistant ID**   | The UUID of your IllumiChat assistant (found in your assistant's Settings page)              |
| **IllumiChat URL** | Leave as the default (`https://app.illumichat.com`) unless you're on a custom domain         |
| **Cookie consent** | Check this to gate widget load on visitor cookie consent (CookieYes / Complianz / WPConsent) |

Enter your Assistant ID and click **Save settings**.

#### Step 3: Connect to WooCommerce

After saving your Assistant ID, a **Connect IllumiChat** button appears.

Click it. You'll be redirected to WooCommerce's consent screen:

> *"Would you like to grant \[IllumiChat] read\_write access to your store?"*

Click **Approve**. WooCommerce sends credentials to IllumiChat and redirects you back to the WordPress plugin settings page, which now shows:

> *Connected. Assistant ID: \[your-uuid]. Widget on storefront: **Enabled**.*

The widget is live on your storefront immediately.

***

## Widget on Storefront

Once the widget is enabled, the WordPress plugin uses WordPress's `wp_enqueue_scripts` hook to inject a loader script into every storefront page footer — no theme edits required.

The script is automatically excluded from **WP Rocket's** JS delay and combine lists. For other caching plugins (LiteSpeed Cache, W3 Total Cache), exclude the widget loader URL from any "Delay JS" or "Combine JS" rules, then flush your cache.

### Manual Snippet (no plugin)

If you prefer not to use the plugin, copy the embed snippet from your WooCommerce channel settings page and paste it before the `</body>` tag in your theme's `footer.php` or via a snippet plugin like **WPCode**.

***

## AI Actions

Each action can be enabled or disabled independently from **Settings → Channels → WooCommerce**.

| Action               | Default | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| **Product Search**   | On      | Searches your catalog; returns product name, price, and link |
| **Order Tracking**   | On      | Looks up order status by order number or email               |
| **Cart Management**  | Off     | Creates carts, adds/removes items, shares checkout link      |
| **Customer Updates** | Off     | Looks up and updates customer billing/shipping/contact info  |

<Note>
  **Cart Management** requires the **CartFlows** or **Cart Abandonment Recovery** plugin on your WooCommerce store. WooCommerce does not natively expose abandoned cart data via its REST API.
</Note>

**Example conversations — Product Search:**

* "What laptops do you have?"
* "Show me dresses under \$50"

**Example conversations — Order Tracking:**

* "Where's my order #1042?"
* "Can you check my recent order? My email is [jane@example.com](mailto:jane@example.com)"

**Example conversations — Cart Management:**

* "Add the blue hoodie in medium to my cart"
* "What's in my cart right now?"

**Example conversations — Customer Updates:**

* "Update my shipping address to 123 Main St, New York, NY 10001"
* "What email do you have on file for me?"

***

## Analytics

Track usage from the **Channels → WooCommerce** analytics dashboard.

| Metric            | What it counts                            |
| ----------------- | ----------------------------------------- |
| Product Searches  | Times the assistant searched your catalog |
| Order Lookups     | Order status inquiries                    |
| Cart Actions      | Cart creates, additions, and removals     |
| Customer Updates  | Customer data lookups and modifications   |
| Webhooks Received | Store events delivered by WooCommerce     |

Filter by **7 days**, **30 days**, or **90 days**.

***

## Managing Your Integration

**Enable / Disable** — Toggle the integration on or off without losing your configuration. When disabled, AI actions and the widget stop, but the store stays connected.

**Disconnect Store** — Removes stored credentials. Reconnect at any time via the OAuth flow.

**Test Connection** — Verifies your credentials are valid and the store is reachable.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Install widget via plugin&#x22; returns an error (404)">
    The plugin's REST endpoint wasn't found. Work through this checklist in order:

    1. **Flush permalinks** — In WordPress, go to **Settings → Permalinks** and click **Save Changes**. This is required after activating any plugin that adds REST routes. It's the most common cause of this error.
    2. **Confirm the plugin is active** — In WordPress admin, go to **Plugins** and verify IllumiChat shows as "Active".
    3. **Check WooCommerce is active** — The plugin's REST endpoint authenticates via WooCommerce's API middleware. WooCommerce must be installed and active.
    4. **Check for REST API security plugins** — Wordfence, "Disable REST API", and similar plugins can block all REST endpoints. Temporarily disable them to test.
    5. **Check permalink structure** — "Plain" permalinks (`?p=123`) disable the REST API entirely. Choose any other option under Settings → Permalinks.
  </Accordion>

  <Accordion title="Widget not appearing on the storefront">
    * Verify the plugin is active and you clicked **Install widget via plugin** successfully (check for a green success message in IllumiChat)
    * **Caching plugins**: flush your cache and exclude the widget loader URL from JS delay/combine rules. WP Rocket is handled automatically; for other plugins (LiteSpeed, W3TC), add the exclusion manually.
    * **Cookie consent**: if cookie consent is enabled in the plugin settings, the widget waits for visitor consent. Test in an incognito window or disable the consent toggle temporarily.
    * **Hosting CSP / firewall**: some managed hosts block external scripts. Whitelist `app.illumichat.com` (or your IllumiChat URL) in your hosting firewall or CSP header.
  </Accordion>

  <Accordion title="&#x22;unable to send the consumer data&#x22; on the WooCommerce consent screen">
    WooCommerce couldn't POST credentials back to IllumiChat after you clicked Approve. Causes:

    * **Firewall blocking outbound POST**: your hosting provider blocks outbound HTTP connections from the server. Contact your host to whitelist IllumiChat's IP range, or try on a different network.
    * **Incorrect store URL**: the URL you entered must match your WordPress site URL exactly (check under **WordPress admin → Settings → General → WordPress Address**).
    * **Session expired**: the OAuth session has a 15-minute window. If you took more than 15 minutes on the consent screen, start over.
  </Accordion>

  <Accordion title="AI actions not working in conversations">
    * Confirm the store status is **Connected** (green) on the Channels overview
    * Check that the specific action toggle is **on** — e.g., Product Search defaults to On but Cart Management defaults to Off
    * Click **Test Connection** to verify credentials are still valid
    * If the test fails, disconnect and reconnect to issue fresh credentials
  </Accordion>

  <Accordion title="The Connect button in the WordPress plugin is greyed out">
    You need to save an **Assistant ID** first. Enter your assistant's UUID in the Assistant ID field on the **WooCommerce → IllumiChat** settings page and click **Save settings** — the Connect button will then become active.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Widget Customization" icon="paintbrush" href="/guides/widget-customization">
    Customize the look and feel of the chat widget on your storefront.
  </Card>

  <Card title="Effective Prompts" icon="wand-magic-sparkles" href="/guides/effective-prompts">
    Write better system prompts to get the most out of your WooCommerce assistant.
  </Card>
</CardGroup>


# Workspaces
Source: https://docs.illumichat.com/features/workspaces

Organize your work with dedicated workspaces

Workspaces are separate environments that let you organize your work in IllumiChat. Each workspace has its own assistants, chat history, projects, contacts, and settings. Use workspaces to separate different clients, teams, departments, or use cases.

## Creating a Workspace

<Steps>
  <Step title="Open the workspace switcher">
    Click on your workspace name in the top-left corner of the sidebar.
  </Step>

  <Step title="Create a new workspace">
    Select **Create Workspace** from the dropdown menu.
  </Step>

  <Step title="Enter workspace details">
    Give your workspace a name and an optional description, then confirm.
  </Step>
</Steps>

You are automatically assigned the **Owner** role for any workspace you create.

## Switching Between Workspaces

Click on the workspace name in the top-left corner of the sidebar to see all workspaces you belong to. Select a workspace to switch to it. Each workspace maintains its own:

* Conversation history across every channel
* Custom assistants
* Knowledge bases and documents
* Contacts
* Member list and roles
* Settings and configuration

## Workspace Settings

Owners and admins can manage workspace settings by navigating to **Settings** in the sidebar.

* **Rename** the workspace
* **Update the description** to help members understand its purpose
* **Delete the workspace** (owner only) -- this permanently removes all data

<Warning>
  Deleting a workspace is irreversible. All assistants, chats, projects, documents, and contacts within the workspace will be permanently removed.
</Warning>

## Role-Based Access Control

Every workspace member is assigned a role that determines what they can do.

| Role       | Description                     | Key Permissions                                                |
| ---------- | ------------------------------- | -------------------------------------------------------------- |
| **Owner**  | Full control over the workspace | Billing, delete workspace, manage all settings, manage members |
| **Admin**  | Day-to-day management           | Manage members, assistants, projects, and settings             |
| **Member** | Standard usage                  | Use assistants, create chats, view shared content              |
| **Guest**  | Limited access                  | Read-only access to select resources                           |

<Note>
  Every workspace must have at least one owner. If you need to step down, transfer ownership first.
</Note>

## Managing Members

### Inviting Members

<Steps>
  <Step title="Go to Settings">
    Open **Settings** from the sidebar, then select the **Members** tab.
  </Step>

  <Step title="Click Invite">
    Click the **Invite** button.
  </Step>

  <Step title="Enter details">
    Enter the person's email address and choose a role (Admin, Member, or Guest).
  </Step>

  <Step title="Send the invitation">
    Confirm to send the invitation. The invitee will receive an email with a link to join.
  </Step>
</Steps>

### Changing a Member's Role

Owners and admins can change a member's role from the **Members** tab in Settings. Click on a member's current role to select a new one.

### Removing Members

To remove a member, go to the **Members** tab in Settings and click the remove option next to the member's name. Removed members immediately lose access to the workspace.

<Tip>
  Create separate workspaces for different projects, clients, or departments. This keeps your assistants, documents, and conversations organized and ensures each team only sees what is relevant to them.
</Tip>


# Zapier Integration
Source: https://docs.illumichat.com/features/zapier

Connect IllumiChat to 7,000+ apps with no-code Zapier automations

Connect IllumiChat to [Zapier](https://zapier.com) to automate your workflows across more than 7,000 apps — no code required. Push new leads into your CRM, alert your team in Slack when a ticket is created, sync conversations to a spreadsheet, or have your assistant follow up automatically.

<Note>
  The Zapier integration requires a **Pro plan or higher**. It authenticates with a **workspace API key**, so any Zap you build acts on behalf of your workspace rather than an individual user.
</Note>

## How It Works

IllumiChat exposes **triggers** (events that start a Zap) and **actions** (steps a Zap can run in IllumiChat). You combine them with any other app Zapier supports.

<Steps>
  <Step title="Create a workspace API key">
    In IllumiChat, go to **Settings → API Keys** and create a key. It starts with `wsk_live_`. Copy it somewhere safe — you will only see it once.
  </Step>

  <Step title="Connect IllumiChat in Zapier">
    In the Zapier editor, add IllumiChat as a trigger or action and choose **Connect a new account**. Paste your API key into the connection wizard.
  </Step>

  <Step title="Build your Zap">
    Pick a trigger (for example, **Lead Captured**) or an action (for example, **Create or Update Contact**), map the fields, and turn the Zap on.
  </Step>
</Steps>

## API Key Scopes

When you create the API key, grant the scopes for the features your Zaps use. The connection wizard reminds you of these:

| Scope            | Needed for                                                          |
| ---------------- | ------------------------------------------------------------------- |
| `events:read`    | All triggers (Lead Captured, Conversation Event) and sample data    |
| `contacts:write` | The **Create or Update Contact** action and **Find Contact** search |
| `tickets:write`  | The **Create Ticket** and **Update Ticket** actions                 |
| `chat:write`     | The **Send Message to Conversation** action                         |

<Tip>
  If a Zap fails to connect or returns a `403`, check that your key carries the scope listed above and that your workspace is on a Pro plan or higher.
</Tip>

## Triggers

Triggers are **instant** — IllumiChat pushes events to Zapier the moment they happen, so your Zaps run in real time rather than polling on a schedule.

### Lead Captured

Starts a Zap whenever a new contact is created — whether a visitor submits the widget lead form or a contact is added to your CRM. The trigger normalizes both into a single contact record so your downstream steps see consistent fields.

**Output fields:** `id`, `name`, `email`, `phone`, `source`, `isNew`, `createdAt`, `assistantId`, `assistantName`.

The trigger fires for leads from every assistant in the workspace; use the `assistantId` / `assistantName` output fields with a Zapier Filter step if you need to narrow to one assistant.

**Example Zaps:**

* New lead → create a row in Google Sheets
* New lead → add a contact in HubSpot and notify `#sales` in Slack
* New lead → send a welcome email via Gmail

### Conversation Event

A single trigger covering the conversation lifecycle. Pick which event fires the Zap from the **Event Type** dropdown:

| Event                           | Fires when                                     |
| ------------------------------- | ---------------------------------------------- |
| `ticket.created`                | A support ticket is opened                     |
| `ticket.assigned`               | A ticket is assigned to an agent               |
| `ticket.status_changed`         | A ticket's status changes                      |
| `live_chat.session_queued`      | A conversation is queued for a human agent     |
| `live_chat.agent_assigned`      | A human agent picks up a live chat             |
| `live_chat.session_transferred` | A live chat is handed to another agent         |
| `live_chat.session_ended`       | A live chat session ends                       |
| `chat.conversation_started`     | A new in-app conversation begins               |
| `widget.conversation_started`   | A website visitor starts a widget conversation |

Events fire workspace-wide; to narrow to one assistant, add a Zapier Filter step on the assistant fields in the event payload.

**Example Zaps:**

* New ticket → create an issue in Linear or Jira
* Ticket assigned → DM the assignee in Slack
* Live chat queued → alert your support team in Slack or Microsoft Teams
* Live chat ended → log the completed session to a spreadsheet or CRM
* Widget conversation started → notify `#sales` that a visitor is chatting

## Actions

### Create or Update Contact

Adds a contact to your IllumiChat CRM or updates an existing one (matched by email). Useful for keeping IllumiChat in sync with leads that originate in other tools.

Requires the `contacts:write` scope.

**Example Zap:** New Typeform submission → **Create or Update Contact** in IllumiChat.

### Create Ticket

Creates a support ticket in IllumiChat. Tickets created this way start in status `new` with source `api`.

Optionally link the ticket to an existing CRM contact by email. The action fails if no contact matches — add a **Find or Create Contact** step before it when the contact might not exist yet.

Requires the `tickets:write` scope.

**Example Zap:** New angry review in Trustpilot → **Create Ticket** assigned to your support queue.

### Update Ticket

Updates an existing ticket's status, priority, subject, or description. Map the **Ticket ID** from a Conversation Event trigger (every ticket event includes `data.ticket.id`) or from an earlier Create Ticket step. Setting the status to `resolved` or `closed` also stamps the ticket's resolved/closed time.

Requires the `tickets:write` scope.

**Example Zap:** Jira issue closed → **Update Ticket** to `resolved` in IllumiChat.

### Send Message to Conversation

Sends a message into an existing conversation.

<Warning>
  This action only works on conversations that are in **live-chat takeover** mode (a human agent has taken over from the assistant). Sending to a conversation that is still AI-handled is rejected. Use it to bridge agent replies from another tool, not to inject messages into automated chats.
</Warning>

Requires the `chat:write` scope.

## Searches

### Find Contact

Looks up a contact in your IllumiChat CRM by exact email address. Pair it with **Create or Update Contact** using Zapier's **create if not found** option to get find-or-create behavior in one step.

Requires the `contacts:write` scope.

## Testing With Sample Data

When you click **Test trigger** in the Zap editor, IllumiChat returns a representative payload so you can map fields before any real event fires:

* If your workspace has received a recent event of that type, Zapier shows that **real** payload.
* Otherwise it shows a **fixture** with placeholder values, so you can still build and map your Zap.

## Managing the Connection

* A Zap's connection is tied to the API key you pasted. Revoking that key in **Settings → API Keys** disconnects every Zap using it.
* Turning a Zap off in Zapier automatically removes its event subscription in IllumiChat, so you stop receiving deliveries for it.
* The Zapier "account" label shows your workspace name, so you can tell multiple workspace connections apart.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection fails when I paste my API key">
    Confirm the key starts with `wsk_live_`, has not been revoked, and that your workspace is on a Pro plan or higher. The connection test also requires the `events:read` scope.
  </Accordion>

  <Accordion title="403 plan_upgrade_required">
    The Zapier integration is gated to Pro and above. Upgrade your workspace plan, then reconnect the account in Zapier.
  </Accordion>

  <Accordion title="My trigger does not fire">
    Make sure the Zap is turned on and that you are generating the event in the right workspace (the connection is tied to one workspace's API key).
  </Accordion>

  <Accordion title="Send Message action is rejected">
    The conversation must be in live-chat takeover mode. The action cannot post into a conversation that the assistant is still handling automatically.
  </Accordion>

  <Accordion title="Create Ticket fails with contact_not_found">
    The **Contact Email** field only links to contacts that already exist in your CRM. Add a **Find or Create Contact** step before the Create Ticket step, or leave the field blank to create the ticket without a contact link.
  </Accordion>
</AccordionGroup>


# Writing Effective Prompts
Source: https://docs.illumichat.com/guides/effective-prompts

Tips for getting the best results from your AI conversations

Well-crafted system prompts are the key to getting consistent, high-quality responses from your IllumiChat assistants. This guide covers practical techniques for writing prompts that produce reliable results.

## System Prompt Basics

A system prompt defines your assistant's personality, knowledge boundaries, and response style. It is set once in the assistant configuration and applies to every conversation.

### Structure Your Prompt

Organize your system prompt into clear sections:

```text theme={null}
## Role
You are a helpful customer support agent for Acme Corp.

## Knowledge
- Our return policy allows returns within 30 days of purchase.
- Shipping takes 3-5 business days for standard orders.
- Premium members get free expedited shipping.

## Tone
- Be friendly and professional.
- Use simple language — avoid jargon.
- Keep responses concise (2-3 paragraphs max).

## Rules
- Never make up information about products.
- If you don't know something, say so and offer to connect the user with a human agent.
- Do not discuss competitor products.
```

## Prompt Writing Techniques

### Be Specific

Vague instructions produce unpredictable results. Compare:

| Weak              | Strong                                                                                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Be helpful"      | "Answer questions about our product pricing and features. If a question is outside your scope, direct the user to [support@example.com](mailto:support@example.com)." |
| "Keep it short"   | "Respond in 1-3 sentences unless the user asks for a detailed explanation."                                                                                           |
| "Be professional" | "Use a friendly, professional tone. Address users by name when available. Avoid slang and emojis."                                                                    |

### Define Boundaries

Tell the assistant what it should **not** do:

```text theme={null}
## Boundaries
- Do not provide medical, legal, or financial advice.
- Do not share internal pricing or discount codes unless the user provides a valid promo code.
- If asked about topics outside our product, politely redirect the conversation.
```

### Provide Examples

Show the assistant what good responses look like:

```text theme={null}
## Example Interactions

User: "How much does the Pro plan cost?"
Assistant: "The Pro plan is $49/month when billed annually, or $59/month
on a monthly plan. It includes unlimited projects, priority support,
and advanced analytics. Would you like to start a free trial?"

User: "Can I get a discount?"
Assistant: "We offer a 20% discount on annual billing. If you have a
promo code, I can apply it to your account. Would you like me to
help with that?"
```

### Use Conditional Logic

Handle different scenarios with clear if/then instructions:

```text theme={null}
## Conditional Responses
- If the user mentions cancellation, ask about their reason before
  processing and offer relevant alternatives.
- If the user is on a free plan and asks about premium features,
  explain the feature and link to the upgrade page.
- If the user reports a bug, collect the steps to reproduce, their
  browser/OS, and create a support ticket.
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the role and goal">
    Begin every system prompt with a clear role statement and the assistant's primary objective. This anchors all subsequent instructions.

    ```text theme={null}
    You are a product specialist for Acme Corp. Your goal is to help
    users understand our products and guide them toward the right
    solution for their needs.
    ```
  </Accordion>

  <Accordion title="Use knowledge bases for factual content">
    Instead of embedding large amounts of product data directly in the prompt, put it in the assistant's [Knowledge Base](/features/knowledge-base). This keeps your prompt focused on behavior while the retrieval system handles facts.

    ```text theme={null}
    ## Knowledge
    Use the attached knowledge base to answer product questions.
    Always cite specific documentation when possible.
    If the knowledge base does not contain the answer, say:
    "I don't have that information. Let me connect you with our team."
    ```
  </Accordion>

  <Accordion title="Control response length">
    Be explicit about how long responses should be:

    ```text theme={null}
    - For simple questions, respond in 1-2 sentences.
    - For how-to questions, use numbered steps (max 5 steps).
    - For comparisons, use a table.
    - Never exceed 300 words in a single response.
    ```
  </Accordion>

  <Accordion title="Test and iterate">
    After setting up your assistant:

    1. Test with 10-15 representative questions.
    2. Note where responses are off-target.
    3. Add or refine instructions to address those gaps.
    4. Repeat until responses are consistently good.
  </Accordion>
</AccordionGroup>

## Common Patterns

### FAQ Assistant

```text theme={null}
You are a FAQ assistant for Acme Corp. Answer user questions based on
the provided knowledge base. If the answer is in the knowledge base,
respond directly. If not, say "I don't have information about that"
and suggest contacting support@acme.com.

Keep answers under 3 sentences. Use bullet points for multi-part answers.
```

### Sales Assistant

```text theme={null}
You are a sales assistant for Acme Corp. Help potential customers
understand our products and find the right plan.

Guidelines:
- Highlight benefits over features.
- Ask qualifying questions (team size, use case, budget).
- Recommend the most appropriate plan based on their answers.
- Provide pricing only from the official pricing page.
- End conversations with a clear call to action (free trial, demo, contact sales).
```

### Technical Support

```text theme={null}
You are a technical support agent for Acme Corp's developer platform.

Guidelines:
- Ask for error messages, stack traces, or screenshots when relevant.
- Provide step-by-step troubleshooting instructions.
- Include code examples when helpful.
- If the issue requires escalation, collect all relevant details
  and create a support ticket.
- Reference documentation links when available.
```

<Tip>
  Combine system prompts with [realtime knowledge sources](/features/knowledge-base) — Shopify, WooCommerce, or a spreadsheet — to give your assistant live order and product data, reducing the need to hard-code information into the prompt.
</Tip>


# Build a Sales Assistant
Source: https://docs.illumichat.com/guides/sales-assistant

Create an AI-powered sales assistant that qualifies leads, answers product questions, and captures contact information through your website widget.

## Overview

A sales assistant helps your website visitors get immediate answers to product questions, qualifies them as potential leads, and captures their contact information -- all without requiring a human sales rep to be online. This guide walks you through creating and deploying one from scratch.

## What You Will Build

By the end of this guide, you will have:

* An AI assistant with a sales-focused system prompt
* A knowledge base loaded with your product information
* An embeddable widget configured with a lead capture form
* Analytics to monitor lead quality and conversation performance

## Step-by-Step Setup

<Steps>
  <Step title="Create the Assistant">
    Go to your workspace and click **New Assistant**. Give it a name like "Sales Assistant" or your company name followed by "Sales."
  </Step>

  <Step title="Write the System Prompt">
    The system prompt defines how your assistant behaves. For a sales assistant, focus on being helpful, asking qualifying questions, and guiding visitors toward next steps.

    Here is a template you can customize:

    ```
    You are a friendly and knowledgeable sales assistant for [Company Name].
    Your goal is to help website visitors understand our products and services,
    answer their questions accurately, and guide qualified prospects toward
    next steps.

    Key behaviors:
    - Be warm, professional, and conversational
    - Answer product questions using your knowledge base
    - Ask clarifying questions to understand the visitor's needs
    - When appropriate, suggest scheduling a demo or speaking with sales
    - If you don't know something, say so honestly and offer to connect
      them with the team
    - Never make up pricing, features, or commitments

    Qualifying questions to naturally work into the conversation:
    - What problem are they trying to solve?
    - How many team members would use the product?
    - What is their timeline for making a decision?
    - Have they used similar products before?

    When a visitor seems qualified (clear need, reasonable timeline, decision-making
    authority), encourage them to fill out the contact form or schedule a demo.
    ```
  </Step>

  <Step title="Connect a Knowledge Base">
    Create a project and upload your product documentation, pricing pages, FAQ documents, feature comparisons, and case studies. Then connect the project to your sales assistant.

    The assistant uses this knowledge base to answer product-specific questions accurately rather than making up information.

    Good content to upload:

    * Product feature descriptions
    * Pricing tiers and comparison tables
    * FAQ documents
    * Case studies and testimonials
    * Integration documentation
    * Competitor comparison sheets
  </Step>

  <Step title="Configure the Widget">
    Go to your assistant's **Widget Settings** and configure:

    1. **Enable the widget** -- Toggle widget access on
    2. **Set allowed domains** -- Add your website domain(s)
    3. **Welcome message** -- Write a greeting that encourages engagement:
       ```
       Hi there! I'm here to help you learn about [Product]. What brings you here today?
       ```
    4. **Suggested questions** -- Add 3-4 common questions visitors ask:
       * "What does \[Product] do?"
       * "How much does it cost?"
       * "Can I see a demo?"
       * "How is this different from \[Competitor]?"
  </Step>

  <Step title="Set Up Lead Capture">
    Open the assistant's **Forms** page, stay on the **Lead Capture** tab, and turn on **Enable Form**. Then add the fields you want to collect:

    | Field                       | Field type       |   Recommended  | Notes                                                                    |
    | --------------------------- | ---------------- | :------------: | ------------------------------------------------------------------------ |
    | Name                        | Single-line text |       Yes      | First and last name                                                      |
    | Email                       | Email            | Yes (required) | Primary contact method                                                   |
    | Phone                       | Phone            |    Optional    | Useful for high-intent leads                                             |
    | Company                     | Single-line text |   Recommended  | Helps sales team prepare                                                 |
    | What are you interested in? | Dropdown         |   Recommended  | Set **Save answer to** to **Lead interest** so you can group leads by it |

    Choose when the form appears under **When to Show Form** -- **After messages** is the usual pick for a sales assistant (recommended: 3-5 messages), so the visitor is engaged before you ask. See [Forms](/widget/configuration#forms) for the full list of field types and triggers.
  </Step>

  <Step title="Deploy to Your Website">
    Add the widget script tag to your website:

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

    See the [Widget Installation](/widget/installation) guide for platform-specific instructions.
  </Step>
</Steps>

## Monitoring Performance

After deploying your sales assistant, monitor these metrics in the IllumiChat dashboard:

| Metric                         | What It Tells You      | Target                  |
| ------------------------------ | ---------------------- | ----------------------- |
| Conversations started          | Widget engagement rate | Growing over time       |
| Avg. messages per conversation | Depth of engagement    | 4-8 messages            |
| Lead form completions          | Conversion rate        | 10-30% of conversations |
| Response accuracy              | Quality of answers     | Review weekly           |

### Improving Lead Quality

<Accordion title="Refine the system prompt">
  If you are getting too many unqualified leads, add more qualifying criteria to the system prompt. If you are getting too few leads, make the prompt more encouraging and lower the bar for suggesting the contact form.
</Accordion>

<Accordion title="Update the knowledge base">
  Review conversations where the assistant could not answer a question. Add that information to your knowledge base to improve future responses.
</Accordion>

<Accordion title="Optimize suggested questions">
  Track which suggested questions lead to the highest conversion rates and prioritize those. Remove questions that lead to dead-end conversations.
</Accordion>

<Accordion title="Set up webhook notifications">
  Configure a webhook for the `contact.created` event to get instant notifications when a new lead is captured. Route these to your CRM or Slack channel for immediate follow-up.
</Accordion>

<Warning>
  Review your sales assistant's conversations regularly. AI-generated responses should be factually accurate. If you notice the assistant making claims about pricing, features, or timelines that are incorrect, update your knowledge base and system prompt immediately.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Widget Customization" icon="palette" href="/guides/widget-customization">
    Customize colors, position, and branding to match your website
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Send lead data to your CRM in real time
  </Card>
</CardGroup>


# Managing the IllumiChat Shopify app
Source: https://docs.illumichat.com/guides/shopify-app-management

Install IllumiChat, enable the chat widget via theme app embeds, and manage it from Shopify admin.

## Install

1. Install IllumiChat from the [Shopify App Store](https://apps.shopify.com/illumichat-v2), or connect your store from IllumiChat under **Knowledge Base → Realtime data → Shopify**.

## Turn on the chat widget

IllumiChat adds the widget as a Shopify **theme app embed** — no code changes to your theme.

1. In Shopify admin, go to **Online Store → Themes**.
2. Click **Customize** on your live theme.
3. Open the **App embeds** tab at the bottom of the left sidebar.
4. Toggle on **IllumiChat Widget**.
5. Click **Save**.

(From IllumiChat, the **Enable in theme editor** button takes you straight to this screen.)

> The widget shows for the store connected to the assistant. If you have multiple stores, connect each store to its own assistant.

## Turn off / uninstall

* **Hide the widget:** in the theme editor's **App embeds** tab, toggle **IllumiChat Widget** off and Save.
* **Uninstall the app:** Shopify admin → **Settings → Apps and sales channels → IllumiChat → Uninstall**.

## Troubleshooting

* **Widget not showing:** confirm the app embed is toggled on in the live theme, and that the assistant is enabled in IllumiChat.
* **Changed themes:** re-enable the app embed on the new theme (app embeds are per-theme).


# Building a Support Assistant
Source: https://docs.illumichat.com/guides/support-assistant

Create an AI-powered customer support assistant step by step

This guide walks through creating a customer support assistant from scratch, including configuring its behavior, connecting a knowledge base, and deploying it as a website widget.

## What You Will Build

By the end of this guide, you will have:

* A support assistant that answers questions using your help documentation
* A knowledge base loaded with your support articles
* A widget embedded on your website for customers to chat with

## Prerequisites

* An IllumiChat account with an active workspace
* Help documentation or FAQ content (PDF, DOCX, or text files)
* Access to your website's HTML to embed the widget

## Step 1: Create the Assistant

<Steps>
  <Step title="Navigate to Assistants">
    Open your workspace and click **Assistants** in the sidebar. Click **Create Assistant**.
  </Step>

  <Step title="Configure basic settings">
    * **Name**: Give it a descriptive name, e.g. "Customer Support"
    * **Visibility**: Controls who on your team can use the assistant in the internal Chat workspace (`workspace` or `private`). It has no effect on the widget -- that's enabled separately in [Step 4](#step-4-deploy-the-widget).
  </Step>

  <Step title="Write the system prompt">
    Use a structured prompt that defines the assistant's role and boundaries:

    ```text theme={null}
    You are a customer support assistant for [Your Company].

    ## Role
    Help customers find answers to their questions using the
    provided knowledge base.

    ## Guidelines
    - Answer questions based on the knowledge base content.
    - Be friendly, concise, and professional.
    - If you cannot find the answer, say so honestly and suggest
      contacting support at [your-email].
    - Never make up information about products, pricing, or policies.

    ## Response Format
    - Use short paragraphs (2-3 sentences).
    - Use bullet points for lists.
    - Include links to relevant help articles when available.
    ```
  </Step>

  <Step title="Save the assistant">
    Click **Save** to create your assistant.
  </Step>
</Steps>

## Step 2: Add a Knowledge Base

Upload your support documentation so the assistant can reference it when answering questions.

<Steps>
  <Step title="Open the assistant's Knowledge Base">
    From your assistant, open the **Knowledge Base** tab. Knowledge belongs to the assistant directly — there is nothing separate to create and attach.
  </Step>

  <Step title="Add your files">
    Under **Static knowledge**, open the **Files** source and drop in your support documents — PDF, Word, Excel, PowerPoint, text, Markdown, CSV and more (see [Supported File Types](/features/knowledge-base#supported-file-types)).
  </Step>

  <Step title="Confirm each source is in use">
    Uploaded files are chunked and indexed on upload, so they are searchable straight away. Each source shows **In use** when it is ready, **Syncing** while it is still working, or **Needs attention** if something failed.
  </Step>
</Steps>

<Note>
  The assistant will now use retrieval-augmented generation (RAG) to search your documents before responding. This means answers are grounded in your actual content rather than the model's general knowledge.
</Note>

## Step 3: Test the Assistant

Before deploying, test the assistant with realistic questions:

1. Open the assistant and start a new chat
2. Ask questions your customers typically ask
3. Verify the responses are accurate and cite the right sources
4. Test edge cases — questions the knowledge base does **not** cover

**What to check:**

* Does it answer correctly from the knowledge base?
* Does it gracefully handle questions outside its scope?
* Is the tone consistent with your brand?
* Are responses the right length?

If responses are off, refine your system prompt. See [Writing Effective Prompts](/guides/effective-prompts) for techniques.

## Step 4: Deploy the Widget

Embed the assistant on your website so customers can chat with it directly.

<Steps>
  <Step title="Get the widget script">
    In your assistant's settings, go to the **Widget** tab. Copy the embed script:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="YOUR_ASSISTANT_ID"
      async
    ></script>
    ```
  </Step>

  <Step title="Add to your website">
    Paste the script before the closing `</body>` tag on every page where you want the widget to appear.
  </Step>

  <Step title="Configure appearance">
    Customize the widget's look using data attributes:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="YOUR_ASSISTANT_ID"
      data-primary-color="#0066FF"
      data-position="bottom-right"
      async
    ></script>
    ```

    See [Widget Configuration](/widget/configuration) for all options.
  </Step>

  <Step title="Set up domain restrictions">
    For security, restrict the widget to your domains. In the assistant's **Widget** settings, add your domains under **Allowed Domains** (e.g., `example.com`, `www.example.com`).
  </Step>
</Steps>

## Step 5: Enable Lead Capture (Optional)

Collect visitor information before or during conversations:

1. Open your assistant's **Forms** page and turn on **Enable Form** on the **Lead Capture** tab
2. Add the fields to collect -- name as **Single-line text**, plus the **Email** and **Phone** types, which validate themselves
3. Mark required fields
4. Leads are saved to your [Contacts](/features/contacts) and can be exported

See [Forms](/widget/configuration#forms) for every field type and for the rules that control when the form appears.

## Step 6: Monitor and Improve

After deployment, review conversations regularly to improve quality:

* **Review chat history** in the IllumiChat dashboard to see what customers are asking
* **Update your knowledge base** when you notice gaps in coverage
* **Refine the system prompt** based on recurring issues
* **Check the widget analytics** for usage patterns

<Tip>
  Set up a [support ticket workflow](/features/tickets) so the assistant can create tickets when it cannot resolve an issue, ensuring nothing falls through the cracks.
</Tip>

## Checklist

Use this checklist to verify your support assistant is ready:

* [ ] Assistant created with a clear system prompt
* [ ] Knowledge base uploaded and fully processed
* [ ] Tested with 10+ representative customer questions
* [ ] Widget embedded and rendering correctly on your site
* [ ] Domain restrictions configured
* [ ] Lead capture enabled (if needed)
* [ ] Team members briefed on reviewing chat history


# Setting Up a Team Workspace
Source: https://docs.illumichat.com/guides/team-workspace

Invite members, assign roles, and collaborate with your team

This guide walks through setting up a workspace for your team, inviting members, configuring roles, and organizing shared assistants and projects.

## Creating a Workspace

When you sign up for IllumiChat, a default workspace is created for you. To create an additional workspace:

<Steps>
  <Step title="Open the workspace switcher">
    Click your workspace name in the top-left corner of the sidebar.
  </Step>

  <Step title="Create a new workspace">
    Click **Create Workspace** and enter a name for your team (e.g., "Marketing Team" or "Acme Corp").
  </Step>

  <Step title="Configure settings">
    Set the workspace name and other preferences under **Settings**.
  </Step>
</Steps>

## Inviting Team Members

<Steps>
  <Step title="Go to Members">
    Navigate to **Settings > Members** in your workspace.
  </Step>

  <Step title="Send invitations">
    Click **Invite Member**, enter their email address, and select a role. You can invite multiple people at once.
  </Step>

  <Step title="Members accept the invite">
    Invited users receive an email with a link to join. Once they accept, they appear in your members list.
  </Step>
</Steps>

<Note>
  Only workspace **owners** and **admins** can invite new members.
</Note>

## Understanding Roles

Each member is assigned a role that determines what they can do in the workspace.

| Role       | What They Can Do                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------- |
| **Owner**  | Everything — billing, workspace deletion, member management, all assistant and project operations |
| **Admin**  | Manage members, create and configure assistants, manage projects and settings                     |
| **Member** | Use assistants, create and view chats, access shared projects                                     |
| **Guest**  | Limited read-only access to specific resources                                                    |

### Role Comparison

| Action               | Owner | Admin | Member |  Guest  |
| -------------------- | :---: | :---: | :----: | :-----: |
| Use assistants       |  Yes  |  Yes  |   Yes  | Limited |
| Create chats         |  Yes  |  Yes  |   Yes  |    No   |
| Create assistants    |  Yes  |  Yes  |   No   |    No   |
| Configure assistants |  Yes  |  Yes  |   No   |    No   |
| Manage projects      |  Yes  |  Yes  |   No   |    No   |
| Invite members       |  Yes  |  Yes  |   No   |    No   |
| Remove members       |  Yes  |  Yes  |   No   |    No   |
| Change roles         |  Yes  |  Yes  |   No   |    No   |
| Manage billing       |  Yes  |   No  |   No   |    No   |
| Delete workspace     |  Yes  |   No  |   No   |    No   |

## Organizing Assistants

Create assistants for different team functions and control who can access each one.

### Visibility Settings

Visibility is an internal-Chat access control -- available on plans with the internal Chat workspace -- and has no bearing on the public widget. An assistant is reachable via the widget whenever it's enabled on the assistant's **Embed** tab, regardless of visibility.

| Visibility  | Who Can Access                                | Best For                             |
| ----------- | --------------------------------------------- | ------------------------------------ |
| `workspace` | Active workspace members                      | Team-specific assistants             |
| `private`   | Creator, admins, and explicitly granted users | Sensitive or experimental assistants |

### Suggested Team Setup

Customer Support and Sales Helper are deployed externally via the widget (Embed tab); visibility below just governs who on your team can use each assistant in the internal Chat workspace.

| Assistant        | Purpose                             | Visibility |
| ---------------- | ----------------------------------- | ---------- |
| Customer Support | External support queries            | Workspace  |
| Sales Helper     | Lead qualification and product info | Workspace  |
| Internal KB      | Internal team Q\&A                  | Workspace  |
| HR Assistant     | Employee policy questions           | Private    |

## Sharing Knowledge

Each assistant owns its own knowledge base, so access follows the assistant's visibility rather than a separate permission set. Give an assistant `workspace` visibility when the whole team should be able to use it, and `private` when it should stay with its creator, admins, and people you grant explicitly.

<Tip>
  Keep one assistant per audience rather than one assistant with everything. A support assistant scoped to your public help content answers more accurately than a single assistant holding both customer docs and internal HR policy.
</Tip>

## Managing the Workspace

### Changing Member Roles

1. Go to **Settings > Members**
2. Click on a member
3. Select a new role from the dropdown
4. Changes take effect immediately

### Removing Members

1. Go to **Settings > Members**
2. Click the remove button next to the member
3. Confirm removal

<Warning>
  Removing a member immediately revokes their access. Their existing chats remain in the workspace but they can no longer access them.
</Warning>

### Transferring Ownership

Only the current owner can transfer ownership:

1. Go to **Settings > Members**
2. Click on the member you want to promote
3. Select **Transfer Ownership**
4. Confirm the transfer

You will be downgraded to admin after transferring ownership.

## Billing

Billing is managed at the workspace level by the owner.

1. Go to **Settings > Billing**
2. View your current plan and usage
3. Upgrade, downgrade, or manage payment methods

Each workspace has its own subscription. Widget message quotas, member limits, and available features depend on your plan tier.

## Checklist

Use this checklist when setting up a new team workspace:

* [ ] Workspace created and named
* [ ] Team members invited with appropriate roles
* [ ] Shared assistants created with correct visibility
* [ ] Knowledge base projects created and shared
* [ ] Widget deployed (if using external-facing assistants)
* [ ] Billing configured


# Webhook Integration
Source: https://docs.illumichat.com/guides/webhooks

Set up and consume webhooks from IllumiChat

Webhooks let IllumiChat notify your systems in real time when events occur, such as a new chat message, a ticket being created, or a lead being captured. Instead of polling the API, your server receives an HTTP POST request for each event.

## How Webhooks Work

<Steps>
  <Step title="Register a webhook">
    Provide a URL and select the events you want to receive.
  </Step>

  <Step title="Events occur">
    When a subscribed event happens in IllumiChat, a payload is sent to your URL.
  </Step>

  <Step title="Your server processes the event">
    Your endpoint receives the POST request, verifies it, and takes action.
  </Step>
</Steps>

## Setting Up a Webhook

### Via the Dashboard

1. Go to **Settings > Webhooks** in your workspace
2. Click **Create Webhook**
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to subscribe to
5. Save

### Via the API

```bash theme={null}
curl -X POST https://app.illumichat.com/api/webhooks \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/illumichat",
    "events": ["chat.message.created", "ticket.created", "lead.captured"],
    "active": true
  }'
```

## Event Types

| Event                  | Description                              |
| ---------------------- | ---------------------------------------- |
| `chat.message.created` | A new message was sent in a conversation |
| `chat.session.created` | A new chat session started               |
| `ticket.created`       | A support ticket was created             |
| `ticket.updated`       | A ticket status or assignment changed    |
| `lead.captured`        | A lead was captured from the widget      |
| `contact.created`      | A new contact was added                  |

## Payload Format

Every webhook delivery includes a JSON payload with a consistent structure:

```json theme={null}
{
  "event": "ticket.created",
  "timestamp": "2025-06-15T14:30:00Z",
  "workspaceId": "ws_abc123",
  "data": {
    "id": "tkt_xyz789",
    "subject": "Cannot reset my password",
    "status": "open",
    "priority": "medium",
    "createdAt": "2025-06-15T14:30:00Z"
  }
}
```

| Field         | Type     | Description                                   |
| ------------- | -------- | --------------------------------------------- |
| `event`       | `string` | The event type                                |
| `timestamp`   | `string` | ISO 8601 timestamp of when the event occurred |
| `workspaceId` | `string` | The workspace where the event originated      |
| `data`        | `object` | Event-specific payload                        |

## Handling Webhooks

### Basic Express Server

```javascript theme={null}
const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/illumichat", (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case "ticket.created":
      console.log("New ticket:", data.subject);
      // Create a Jira issue, send a Slack notification, etc.
      break;

    case "lead.captured":
      console.log("New lead:", data.email);
      // Add to CRM, send welcome email, etc.
      break;

    case "chat.message.created":
      console.log("New message in session:", data.sessionId);
      break;

    default:
      console.log("Unhandled event:", event);
  }

  // Always return 200 quickly to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);
```

### Next.js API Route

```typescript theme={null}
// app/api/webhooks/illumichat/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { event, data } = body;

  switch (event) {
    case "ticket.created":
      await handleNewTicket(data);
      break;
    case "lead.captured":
      await handleNewLead(data);
      break;
  }

  return NextResponse.json({ received: true });
}

async function handleNewTicket(data: any) {
  // Your ticket handling logic
}

async function handleNewLead(data: any) {
  // Your lead handling logic
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a `200` response as soon as possible. Process the event asynchronously if your logic takes more than a few seconds. IllumiChat may time out and retry if your endpoint does not respond promptly.
  </Accordion>

  <Accordion title="Handle duplicates">
    Webhook deliveries can occasionally be duplicated. Use the event `timestamp` and resource `id` to deduplicate on your end.

    ```javascript theme={null}
    const processedEvents = new Set();

    function handleWebhook(payload) {
      const key = `${payload.event}:${payload.data.id}:${payload.timestamp}`;
      if (processedEvents.has(key)) return;
      processedEvents.add(key);
      // Process the event
    }
    ```
  </Accordion>

  <Accordion title="Use HTTPS">
    Webhook URLs must use HTTPS. For local development, use a tunneling service like ngrok to expose your local server.

    ```bash theme={null}
    ngrok http 3000
    # Use the generated https://xxxx.ngrok.io/webhooks/illumichat URL
    ```
  </Accordion>

  <Accordion title="Log payloads during development">
    Log the full payload while building your integration so you can inspect the exact structure of each event type.

    ```javascript theme={null}
    app.post("/webhooks/illumichat", (req, res) => {
      console.log(JSON.stringify(req.body, null, 2));
      res.status(200).json({ received: true });
    });
    ```
  </Accordion>
</AccordionGroup>

## Retry Policy

If your endpoint returns a non-2xx status code or times out, IllumiChat retries the delivery with exponential backoff:

| Attempt   | Delay      |
| --------- | ---------- |
| 1st retry | 1 minute   |
| 2nd retry | 5 minutes  |
| 3rd retry | 30 minutes |

After 3 failed retries, the delivery is marked as failed. You can view failed deliveries in your webhook settings and manually trigger a re-delivery.

## Managing Webhooks

### List Active Webhooks

```bash theme={null}
curl https://app.illumichat.com/api/webhooks \
  -H "Authorization: Bearer <your-token>"
```

### Disable a Webhook

```bash theme={null}
curl -X PATCH https://app.illumichat.com/api/webhooks/{webhookId} \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

### Delete a Webhook

```bash theme={null}
curl -X DELETE https://app.illumichat.com/api/webhooks/{webhookId} \
  -H "Authorization: Bearer <your-token>"
```

<Tip>
  Use webhooks together with the [Contacts API](/api/authentication) and [Tickets](/features/tickets) to build automated support workflows — for example, automatically creating a CRM record when a lead is captured and escalating to a human agent when a ticket is created.
</Tip>


# Widget Customization
Source: https://docs.illumichat.com/guides/widget-customization

Customize your IllumiChat widget's appearance, behavior, and branding to match your website.

## Overview

The IllumiChat widget can be customized to match your website's branding and design. This guide covers visual customization through `data-*` attributes, CSS overrides, and programmatic control via the SDK.

## Colors

Set the primary color using the `data-primary-color` attribute. This color is applied to the launcher button, message bubbles, and interactive elements.

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

| Color Value  | Result           |
| ------------ | ---------------- |
| `#6366F1`    | Indigo (default) |
| `#10B981`    | Green            |
| `#F59E0B`    | Amber            |
| `#EF4444`    | Red              |
| Any hex code | Your brand color |

<Tip>
  Choose a color with sufficient contrast against both light and dark backgrounds. The widget automatically adjusts text color for readability.
</Tip>

## Position

Control where the widget launcher appears on the page.

<CodeGroup>
  ```html Bottom Right (Default) theme={null}
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="your-assistant-id"
    data-position="bottom-right"
    async
  ></script>
  ```

  ```html Bottom Left theme={null}
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="your-assistant-id"
    data-position="bottom-left"
    async
  ></script>
  ```
</CodeGroup>

Fine-tune the exact offset from screen edges:

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-offset-x="24"
  data-offset-y="24"
  async
></script>
```

## Suggested Messages

Display clickable message chips that visitors can tap to start a conversation quickly.

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-suggested-messages="What does your product do?,How much does it cost?,Can I see a demo?"
  async
></script>
```

Separate messages with commas. These are displayed as buttons when the chat panel opens.

<Note>
  Keep suggested messages short (under 40 characters each) so they display well on mobile devices. Aim for 3-4 messages.
</Note>

You can also show suggested messages as floating bubbles near the launcher button:

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-suggested-messages="What does your product do?,How much does it cost?"
  data-show-suggested-bubbles="true"
  data-suggested-bubbles-delay="3000"
  async
></script>
```

<Note>
  The easiest way to enable these bubbles is the dashboard: **Widget → Styles →
  Popup messages** lets you set up to 3 dedicated teaser messages and a delay,
  with no embed changes needed. When popup messages are configured there, the
  bubbles show those instead of your suggested messages, and clicking a bubble
  opens the chat. Script-tag attributes still take priority over dashboard
  settings. See [Popup Messages](/widget/configuration#popup-messages).
</Note>

## Auto-Open

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

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-auto-open="5000"
  async
></script>
```

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

## Launcher Icon

Customize the launcher button icon:

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-launcher-icon="chat"
  data-company-name="Acme Corp"
  async
></script>
```

## Custom CSS

For advanced styling, you can target the widget's shadow DOM elements using CSS custom properties (CSS variables).

```html theme={null}
<style>
  illumichat-widget {
    --ic-font-family: 'Inter', system-ui, sans-serif;
    --ic-border-radius: 12px;
    --ic-launcher-size: 56px;
    --ic-launcher-margin: 20px;
  }
</style>
```

| CSS Variable           | Default     | Description                          |
| ---------------------- | ----------- | ------------------------------------ |
| `--ic-font-family`     | `system-ui` | Font family for all widget text      |
| `--ic-border-radius`   | `16px`      | Border radius for the chat window    |
| `--ic-launcher-size`   | `56px`      | Size of the floating launcher button |
| `--ic-launcher-margin` | `16px`      | Distance from screen edges           |

<Warning>
  The widget uses Shadow DOM for style isolation. Standard CSS selectors will not affect widget internals. Use the CSS custom properties listed above for supported customizations.
</Warning>

## Mobile Behavior

The widget automatically adapts to mobile screens:

* On screens narrower than 480px, the chat window expands to full width
* The launcher button is slightly smaller on mobile (48px vs 56px)
* Touch-friendly tap targets and scrolling are enabled

## Programmatic Control

For dynamic control, use the JavaScript SDK to interact with the widget at runtime.

### Control Widget State

```javascript theme={null}
// Get the widget instance
const widget = IllumiChat.getInstance();

// Open the widget
widget.open();

// Close the widget
widget.close();

// Toggle open/close
widget.toggle();

// Send a pre-filled message
widget.sendMessage('I want to learn about enterprise pricing');
```

### React to Events

```javascript theme={null}
const widget = IllumiChat.getInstance();

// Listen for widget events
widget.on('open', () => {
  console.log('Widget opened');
});

widget.on('message:sent', (data) => {
  console.log('User sent:', data.content);
});

widget.on('lead:submitted', (data) => {
  // Track conversion in analytics
  gtag('event', 'lead_captured', {
    contactId: data.contactId,
    source: 'widget',
  });
});
```

See the [SDK Reference](/widget/sdk-reference) for the complete list of methods and events.

## Full Configuration Reference

| Attribute                      | Type   | Default        | Description                                |
| ------------------------------ | ------ | -------------- | ------------------------------------------ |
| `data-assistant-id`            | string | --             | Required. Your assistant ID.               |
| `data-primary-color`           | string | `#6366f1`      | Primary brand color (hex).                 |
| `data-position`                | string | `bottom-right` | `bottom-right` or `bottom-left`.           |
| `data-offset-x`                | string | `20`           | Horizontal offset from edge in pixels.     |
| `data-offset-y`                | string | `20`           | Vertical offset from edge in pixels.       |
| `data-auto-open`               | string | --             | Auto-open delay in milliseconds.           |
| `data-suggested-messages`      | string | --             | Comma-separated suggested messages.        |
| `data-show-suggested-bubbles`  | string | `false`        | Show message bubbles near launcher.        |
| `data-suggested-bubbles-delay` | string | `3000`         | Delay before showing bubbles (ms).         |
| `data-launcher-icon`           | string | `chat`         | Launcher icon URL or `"chat"` for default. |
| `data-company-name`            | string | `Support`      | Company name for accessibility.            |
| `data-auth-mode`               | string | `anonymous`    | `anonymous`, `authenticated`, or `auto`.   |
| `data-persist-session`         | string | `true`         | Persist session across page loads.         |
| `data-visitor-id`              | string | --             | Custom visitor ID for user linking.        |
| `data-base-url`                | string | --             | Override widget iframe URL.                |
| `data-debug`                   | string | `false`        | Enable debug logging to console.           |

## Next Steps

<CardGroup>
  <Card title="Widget Installation" icon="download" href="/widget/installation">
    Install the widget on any website platform
  </Card>

  <Card title="SDK Reference" icon="code" href="/widget/sdk-reference">
    Complete JavaScript API reference for programmatic control
  </Card>
</CardGroup>


# Widget in React & Next.js
Source: https://docs.illumichat.com/guides/widget-react

Add the IllumiChat widget to your React or Next.js application

This guide covers how to integrate the IllumiChat widget into React and Next.js applications, including component patterns, TypeScript support, and programmatic control.

## Basic Next.js Integration

The recommended approach for Next.js uses the `next/script` component:

```tsx theme={null}
// components/IllumiChatWidget.tsx
'use client';

import Script from 'next/script';

export function IllumiChatWidget() {
  return (
    <Script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="YOUR_ASSISTANT_ID"
      strategy="lazyOnload"
    />
  );
}
```

Add it to your root layout so it loads on every page:

```tsx theme={null}
// app/layout.tsx
import { IllumiChatWidget } from '@/components/IllumiChatWidget';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <IllumiChatWidget />
      </body>
    </html>
  );
}
```

<Note>
  The `'use client'` directive is required because `next/script` uses browser APIs. The widget itself is loaded asynchronously and will not affect your server-side rendering.
</Note>

## Configurable Component

Create a reusable component that accepts configuration props:

```tsx theme={null}
// components/IllumiChatWidget.tsx
'use client';

import Script from 'next/script';

interface IllumiChatWidgetProps {
  assistantId: string;
  primaryColor?: string;
  position?: 'bottom-right' | 'bottom-left';
  authMode?: 'anonymous' | 'authenticated' | 'auto';
}

export function IllumiChatWidget({
  assistantId,
  primaryColor,
  position = 'bottom-right',
  authMode = 'anonymous',
}: IllumiChatWidgetProps) {
  return (
    <Script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id={assistantId}
      data-primary-color={primaryColor}
      data-position={position}
      data-auth-mode={authMode}
      strategy="lazyOnload"
    />
  );
}
```

Usage:

```tsx theme={null}
<IllumiChatWidget
  assistantId="your-assistant-id"
  primaryColor="#0066FF"
/>
```

## Programmatic Control

Use the global `IllumiChat` API to control the widget from your React components:

```tsx theme={null}
'use client';

export function SupportButton() {
  const openChat = () => {
    if (typeof window !== 'undefined' && window.IllumiChat) {
      window.IllumiChat.open();
    }
  };

  return (
    <button onClick={openChat}>
      Chat with Support
    </button>
  );
}
```

### TypeScript Declarations

Add type declarations for the global API:

```typescript theme={null}
// types/illumichat.d.ts
interface IllumiChatAPI {
  open(): void;
  close(): void;
  toggle(): void;
  sendMessage(message: string): void;
  on(event: string, callback: (...args: any[]) => void): void;
  off(event: string, callback: (...args: any[]) => void): void;
}

declare global {
  interface Window {
    IllumiChat?: IllumiChatAPI;
  }
}

export {};
```

## Event Handling

Listen to widget events using a custom hook:

```tsx theme={null}
'use client';

import { useEffect } from 'react';

export function useIllumiChatEvents() {
  useEffect(() => {
    const handleOpen = () => console.log('Widget opened');
    const handleClose = () => console.log('Widget closed');
    const handleMessage = (message: string) => {
      console.log('User sent:', message);
    };

    const interval = setInterval(() => {
      if (window.IllumiChat) {
        window.IllumiChat.on('open', handleOpen);
        window.IllumiChat.on('close', handleClose);
        window.IllumiChat.on('message:sent', handleMessage);
        clearInterval(interval);
      }
    }, 100);

    return () => {
      clearInterval(interval);
      if (window.IllumiChat) {
        window.IllumiChat.off('open', handleOpen);
        window.IllumiChat.off('close', handleClose);
        window.IllumiChat.off('message:sent', handleMessage);
      }
    };
  }, []);
}
```

Use it in your layout or page component:

```tsx theme={null}
'use client';

import { useIllumiChatEvents } from '@/hooks/useIllumiChatEvents';

export function WidgetEventListener() {
  useIllumiChatEvents();
  return null;
}
```

## Conditional Loading

Load the widget only on specific pages or for specific users:

```tsx theme={null}
'use client';

import Script from 'next/script';
import { usePathname } from 'next/navigation';

export function IllumiChatWidget({
  assistantId,
}: {
  assistantId: string;
}) {
  const pathname = usePathname();

  // Only show on marketing and support pages
  const showWidget =
    pathname.startsWith('/support') ||
    pathname.startsWith('/pricing') ||
    pathname === '/';

  if (!showWidget) return null;

  return (
    <Script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id={assistantId}
      strategy="lazyOnload"
    />
  );
}
```

## Authenticated Widget

Pass user identity to the widget for authenticated conversations:

```tsx theme={null}
'use client';

import Script from 'next/script';
import { useSession } from 'next-auth/react'; // or your auth provider

export function IllumiChatWidget({
  assistantId,
}: {
  assistantId: string;
}) {
  const { data: session } = useSession();

  return (
    <Script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id={assistantId}
      data-auth-mode={session ? 'authenticated' : 'anonymous'}
      data-visitor-id={session?.user?.id}
      strategy="lazyOnload"
    />
  );
}
```

<Warning>
  Avoid passing sensitive user data through data attributes. The widget is client-side JavaScript and data attributes are visible in the DOM.
</Warning>

## Plain React (non-Next.js)

For React apps without Next.js, load the script manually:

```tsx theme={null}
import { useEffect } from 'react';

export function IllumiChatWidget({
  assistantId,
}: {
  assistantId: string;
}) {
  useEffect(() => {
    if (document.getElementById('illumichat-widget')) return;

    const script = document.createElement('script');
    script.id = 'illumichat-widget';
    script.src = 'https://widget.illumichat.com/v1/widget.js';
    script.async = true;
    script.dataset.assistantId = assistantId;
    document.body.appendChild(script);

    return () => {
      const el = document.getElementById('illumichat-widget');
      if (el) el.remove();
    };
  }, [assistantId]);

  return null;
}
```

## Environment-Based Configuration

Use environment variables to manage different assistants across environments:

```tsx theme={null}
// components/IllumiChatWidget.tsx
'use client';

import Script from 'next/script';

const ASSISTANT_ID = process.env.NEXT_PUBLIC_ILLUMICHAT_ASSISTANT_ID;

export function IllumiChatWidget() {
  if (!ASSISTANT_ID) return null;

  return (
    <Script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id={ASSISTANT_ID}
      strategy="lazyOnload"
    />
  );
}
```

```bash theme={null}
# .env.local
NEXT_PUBLIC_ILLUMICHAT_ASSISTANT_ID=your-dev-assistant-id

# .env.production
NEXT_PUBLIC_ILLUMICHAT_ASSISTANT_ID=your-prod-assistant-id
```

<Tip>
  See the full [Widget SDK Reference](/widget/sdk-reference) for all available methods, events, and configuration options.
</Tip>


# Widget on WordPress
Source: https://docs.illumichat.com/guides/widget-wordpress

Install the IllumiChat chat widget on your WordPress site using the theme editor, a code snippets plugin, or the WordPress Customizer.

## Overview

This guide covers three methods for adding the IllumiChat widget to a WordPress website. Choose the method that best fits your comfort level and site setup.

| Method               | Difficulty | Survives Theme Updates | Best For    |
| -------------------- | :--------: | :--------------------: | ----------- |
| WPCode Plugin        |    Easy    |           Yes          | Most users  |
| WordPress Customizer |    Easy    |    Depends on theme    | Quick setup |
| Theme Editor         |   Medium   |           No           | Developers  |

## Method 1: WPCode Plugin (Recommended)

WPCode (formerly Insert Headers and Footers) is a free plugin that lets you add code snippets without editing theme files.

<Steps>
  <Step title="Install WPCode">
    In your WordPress dashboard, go to **Plugins** > **Add New**. Search for "WPCode" and install the free version. Activate the plugin.
  </Step>

  <Step title="Create a New Snippet">
    Go to **Code Snippets** > **+ Add Snippet**. Click **Add Your Custom Code (New Snippet)** and select **HTML Snippet**.
  </Step>

  <Step title="Add the Widget Code">
    Paste the following code into the snippet editor:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    ```

    Replace `your-assistant-id` with your actual assistant ID from the IllumiChat dashboard.
  </Step>

  <Step title="Configure the Snippet">
    * Set the **Location** to **Site Wide Footer**
    * Set **Status** to **Active**
    * Click **Save Snippet**
  </Step>
</Steps>

***

## Method 2: WordPress Customizer

If your theme supports the Customizer, you can add the widget code there.

<Steps>
  <Step title="Open the Customizer">
    Go to **Appearance** > **Customize** in your WordPress dashboard.
  </Step>

  <Step title="Find Additional CSS/JS Section">
    Look for a section called **Additional JavaScript**, **Custom Code**, or **Footer Scripts**. The exact name depends on your theme.

    <Note>
      Not all themes offer this option. If you don't see a JavaScript or footer scripts section, use the WPCode plugin method instead.
    </Note>
  </Step>

  <Step title="Add the Widget Code">
    Paste the widget script tag:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    ```
  </Step>

  <Step title="Publish">
    Click **Publish** to save your changes. The widget should appear on your site immediately.
  </Step>
</Steps>

***

## Method 3: Theme Editor

You can add the widget code directly to your theme's `footer.php` file. This method requires familiarity with WordPress theme files.

<Warning>
  Changes made directly to theme files are overwritten when the theme is updated. Use a child theme or one of the other methods for a more durable solution.
</Warning>

<Steps>
  <Step title="Open the Theme Editor">
    Go to **Appearance** > **Theme File Editor** in your WordPress dashboard.
  </Step>

  <Step title="Select footer.php">
    In the file list on the right, click **footer.php**.
  </Step>

  <Step title="Add the Widget Code">
    Add the script tag just before the closing `</body>` tag:

    ```php theme={null}
    <!-- IllumiChat Widget -->
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    <?php wp_footer(); ?>
    </body>
    </html>
    ```

    Make sure the script tag appears before `<?php wp_footer(); ?>`.
  </Step>

  <Step title="Update File">
    Click **Update File** to save your changes.
  </Step>
</Steps>

***

## Conditional Loading

You may want the widget to appear only on certain pages. Use WordPress template conditionals to control where the widget loads.

### Using WPCode Conditional Logic

WPCode Pro supports conditional logic natively. In the snippet settings, use the **Smart Conditional Logic** section to restrict the snippet to specific pages, post types, or URLs.

### Using PHP Conditionals

If editing your theme or using a PHP-capable snippet plugin:

```php theme={null}
<?php if (is_page('pricing') || is_page('contact') || is_singular('product')) : ?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php endif; ?>
```

| Conditional              | Description                           |
| ------------------------ | ------------------------------------- |
| `is_page('pricing')`     | Only on a page with slug "pricing"    |
| `is_front_page()`        | Only on the homepage                  |
| `is_singular('product')` | Only on WooCommerce product pages     |
| `is_category()`          | Only on category archive pages        |
| `!is_admin()`            | Everywhere except the admin dashboard |

***

## WooCommerce Integration

If you run a WooCommerce store, you can configure the widget to show product-specific context on product pages.

```php theme={null}
<?php if (is_singular('product')) :
  $product = wc_get_product(get_the_ID());
?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php else : ?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php endif; ?>
```

This shows a product-specific greeting on product pages and the default widget everywhere else.

***

## Troubleshooting

<Accordion title="Widget does not appear after adding the code">
  * Clear your browser cache and any WordPress caching plugin (WP Rocket, W3 Total Cache, etc.)
  * Verify the assistant ID is correct
  * Check the browser console for JavaScript errors
  * Ensure the widget is enabled in the assistant's settings
  * Confirm your domain is in the assistant's allowed domains list
</Accordion>

<Accordion title="Widget appears briefly then disappears">
  * Check if a Content Security Policy (CSP) header is blocking the widget script
  * Add `widget.illumichat.com` and `app.illumichat.com` to your CSP `script-src` and `connect-src` directives
  * Some security plugins (Wordfence, Sucuri) may block external scripts -- add the widget domain to the allowlist
</Accordion>

<Accordion title="Widget conflicts with other chat plugins">
  * If you have another chat widget installed (Intercom, Drift, Tidio), it may conflict with the IllumiChat widget
  * Disable other chat plugins or use conditional loading to show only one widget per page
  * Check for CSS z-index conflicts -- the IllumiChat widget uses `z-index: 2147483647`
</Accordion>

<Accordion title="Caching plugins prevent widget updates">
  * Most caching plugins serve static HTML, which includes the widget script tag
  * If you change the assistant ID or widget configuration, clear the cache after making changes
  * The widget itself loads dynamically and is not cached, only the script tag inclusion is affected
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Widget Customization" icon="palette" href="/guides/widget-customization">
    Customize colors, position, and greeting messages
  </Card>

  <Card title="Widget Configuration" icon="gear" href="/widget/configuration">
    Full reference for all widget configuration options
  </Card>
</CardGroup>


# Help Center
Source: https://docs.illumichat.com/help

Answers to common questions

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I reset my password?">
    1. Go to [app.illumichat.com/login](https://app.illumichat.com/login)
    2. Click **Forgot Password**
    3. Enter your email address
    4. Check your email for a reset link
    5. Click the link and set a new password
  </Accordion>

  <Accordion title="How do I change my email address?">
    Contact [support@illumichat.com](mailto:support@illumichat.com) to request an email change. For security, we verify these requests manually.
  </Accordion>

  <Accordion title="Is my data secure?">
    Yes. All data is encrypted in transit (TLS) and at rest. We don't train AI models on your conversations. See our [Privacy Policy](https://illumichat.com/legal/privacy-policy) for details.
  </Accordion>

  <Accordion title="Can I use Illumichat for my business?">
    Absolutely! Our Pro and Enterprise plans are designed for business use. The Widget feature lets you embed IllumiChat on your website, and the [SMS Integration](/features/sms) lets customers text your AI assistants directly.
  </Accordion>

  <Accordion title="How do I cancel my subscription?">
    Go to **Account Settings → Billing → Cancel Subscription**. You'll keep access until the end of your billing period.
  </Accordion>

  <Accordion title="What file types can I upload?">
    * **Images**: JPG, PNG, GIF, WebP
    * **Documents**: PDF, Word (.docx), PowerPoint (.pptx), text, Markdown
    * **Data**: CSV, Excel (.xlsx), JSON, HTML
    * **Code**: source files in most common languages

    Pre-2007 Office files (.doc, .xls, .ppt) need re-saving as .docx, .xlsx or .pptx first.

    Maximum file size is 10MB per file.
  </Accordion>

  <Accordion title="Why is the AI giving incorrect information?">
    AI models can sometimes make mistakes. For factual accuracy:

    * Add the correct answer to the assistant's [knowledge base](/features/knowledge-base) so it answers from your content instead of guessing
    * Turn on **Strict Mode** so the assistant answers only from its knowledge base
    * Verify important facts independently
    * Provide more context in the assistant's instructions
  </Accordion>

  <Accordion title="How do I clear a conversation out of my inbox?">
    Open the conversation in the [Universal Inbox](/features/inbox) and choose **Resolve** when it is handled, or **Archive** to remove it from the active list. Archived conversations stay searchable.
  </Accordion>

  <Accordion title="Can multiple people use one account?">
    No, accounts are for individual use. For team collaboration, create a workspace and invite your team -- Pro and Enterprise plans support multiple workspaces and shared assistants.
  </Accordion>

  <Accordion title="How does SMS Integration work?">
    SMS Integration connects your Twilio account to an Illumichat assistant. When someone texts your Twilio phone number, your assistant generates an AI response and sends it back via SMS. You provide your own Twilio credentials (BYOK), so messaging costs are billed directly by Twilio. See the [SMS Integration guide](/features/sms) for setup instructions.
  </Accordion>

  <Accordion title="Do I need a paid Twilio account for SMS?">
    A free Twilio trial account works for testing, but trial accounts can only send messages to verified phone numbers. For production use, upgrade to a paid Twilio account and purchase a phone number with SMS capability.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### The app is slow or not responding

1. **Check your internet connection**
2. **Try a different browser** (Chrome, Firefox, Safari, Edge)
3. **Clear browser cache** and refresh the page
4. **Disable browser extensions** that might interfere
5. **Check [status.illumichat.com](https://status.illumichat.com)** for outages

### File upload failing

* Ensure file is under 10MB
* Check that the file type is supported
* Try a different file format
* Refresh the page and try again

### Can't log in

* Verify you're using the correct email
* Check if Caps Lock is on
* Try resetting your password
* Clear browser cookies for illumichat.com
* Try incognito/private browsing

### Widget not appearing on my site

* Verify the domain is authorized in widget settings
* Check the widget ID in your embed code
* Ensure the script is placed before `</body>`
* Check browser console for JavaScript errors

### SMS not working

* Verify Twilio credentials using the **Test Credentials** button
* Check that SMS is **enabled** in your assistant's SMS settings
* Confirm webhook URLs are set correctly in the [Twilio Console](https://console.twilio.com)
* Ensure your Twilio account has sufficient balance
* See the full [SMS Troubleshooting guide](/features/sms#troubleshooting)

## Contact Support

Still need help? Reach out:

<CardGroup>
  <Card title="Email" icon="envelope" href="mailto:support@illumichat.com">
    [support@illumichat.com](mailto:support@illumichat.com)
  </Card>

  <Card title="Response Time" icon="clock">
    We typically respond within 24 hours
  </Card>
</CardGroup>

When contacting support, please include:

* Your account email
* Description of the issue
* Screenshots if applicable
* Browser and device you're using


# Welcome to IllumiChat
Source: https://docs.illumichat.com/introduction

AI customer support across your website widget, messaging channels, and a shared team inbox

IllumiChat is an AI customer-support platform. You build assistants trained on your own content, deploy them on your website and messaging channels, and handle everything your team needs to answer in one shared inbox.

<Note>
  Sign up at [app.illumichat.com](https://app.illumichat.com) to get started.
</Note>

## Explore the Docs

<CardGroup>
  <Card title="Get Started" icon="rocket" href="/quickstart">
    Create your account and send your first message in minutes.
  </Card>

  <Card title="Custom Assistants" icon="robot" href="/features/assistants">
    Build AI personas with custom instructions and knowledge bases.
  </Card>

  <Card title="Knowledge Base" icon="book" href="/features/knowledge-base">
    Ground answers in your files, websites, Q\&A, and live store data.
  </Card>

  <Card title="Widget SDK" icon="window" href="/widget/overview">
    Embed an AI chat widget on your website.
  </Card>

  <Card title="Universal Inbox" icon="inbox" href="/features/inbox">
    Handle every channel in one shared team inbox.
  </Card>

  <Card title="Channels" icon="comments" href="/features/channels">
    Connect WhatsApp, Messenger, Instagram, SMS, and email.
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Build on IllumiChat with our API endpoints.
  </Card>
</CardGroup>

## Key Features

### Powerful AI

IllumiChat is powered by a state-of-the-art AI model. Every conversation uses the same high-quality model, so you get consistent, reliable results across every channel.

### File Attachments

Visitors can attach files to a conversation. IllumiChat can read and analyze images, PDFs, and other documents so your assistant can answer questions about their content.

### Workspaces and Custom Assistants

Organize your work into **workspaces** -- separate environments for different teams, brands, or clients. Within each workspace, create **custom assistants** with tailored instructions, specific knowledge bases, and fine-tuned behavior.

### Knowledge Base and RAG

Connect a **knowledge base** to give your assistants context they can draw from — files, websites, text, and Q\&A pairs, plus live data from Shopify, WooCommerce, and spreadsheets. IllumiChat uses Retrieval-Augmented Generation (RAG) to search your content and provide accurate, grounded answers.

### Universal Inbox

Every channel lands in one shared inbox. Claim conversations, take over from the AI mid-thread, add internal notes, and hand back when you are done.

### Embeddable Widget SDK

Add an AI chat widget to any website with a single script tag. The widget connects to your custom assistants, inherits their instructions and knowledge, and provides a polished chat experience for your visitors.

### SMS Integration

Connect your own Twilio account (BYOK) to let users interact with your assistants over text message. Configure phone numbers, manage sessions, and track analytics from the IllumiChat dashboard.

### Support Tickets

Create and track support tickets directly from conversations. Capture issues, assign priorities, and manage resolution workflows without switching tools.

## Getting Help

<CardGroup>
  <Card title="Help Center" icon="circle-question" href="/help">
    Browse FAQs, troubleshooting guides, and how-to articles.
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@illumichat.com">
    Reach out to our team for personalized assistance.
  </Card>
</CardGroup>

<Tip>
  New to IllumiChat? Head to the [Quickstart guide](/quickstart) to create your account and get your first assistant answering in under five minutes.
</Tip>


# Getting Started
Source: https://docs.illumichat.com/quickstart

Create your account and get your first assistant answering

This guide walks you through creating your IllumiChat account, setting up your first workspace, and building an assistant that can answer questions about your business.

## Create Your Account

<Steps>
  <Step title="Sign Up">
    Go to [app.illumichat.com](https://app.illumichat.com) and click **Sign Up**. You can create an account with your email address or sign in with Google.
  </Step>

  <Step title="Verify Your Email">
    If you signed up with email, check your inbox for a verification link from IllumiChat. Click the link to confirm your address and activate your account.

    <Tip>
      Did not receive the email? Check your spam folder or click **Resend verification** on the sign-in page.
    </Tip>
  </Step>

  <Step title="Set Up Your Workspace">
    After signing in for the first time, you will be prompted to create a **workspace**. A workspace is a shared environment where you and your team organize assistants, knowledge, and conversations.

    Give your workspace a name (for example, your company or team name) and you are ready to go. You can always create additional workspaces later.

    <Note>
      Workspaces keep everything separate -- assistants, knowledge bases, conversations, and members. Use different workspaces for different teams, brands, or clients.
    </Note>
  </Step>
</Steps>

## Your First Assistant

<Steps>
  <Step title="Create the assistant">
    Go to **Assistants** and click **New Assistant**. Give it a name your team will recognize, such as "Support Bot".
  </Step>

  <Step title="Write its instructions">
    Describe how it should behave -- its tone, what it should and should not answer, and when it should hand off to a human. See [Effective Prompts](/guides/effective-prompts) for patterns that work.
  </Step>

  <Step title="Add knowledge">
    Open the assistant's **Knowledge Base** and add the content it should answer from: upload files, crawl your website, paste text, or add Q\&A pairs. Static sources are searchable as soon as they finish uploading.
  </Step>

  <Step title="Test it">
    Use the assistant's test chat to ask questions the way a customer would. Test conversations do not consume credits. See [Testing](/features/testing).
  </Step>
</Steps>

## Adding Knowledge

Your assistant answers from the content you give it. Add sources from the assistant's **Knowledge Base** tab:

* **Files** -- upload documents to be chunked, embedded, and searched
* **Websites** -- crawl pages so their content is indexed
* **Text and Q\&A** -- paste answers directly for questions you get often
* **Live data** -- connect Shopify, WooCommerce, or a spreadsheet to read order and product data at question time

For the full list of accepted formats and extraction caveats, see [Supported File Types](/features/knowledge-base#supported-file-types).

<Tip>
  Start with the ten questions your customers actually ask most. A small, accurate knowledge base beats a large, noisy one.
</Tip>

## Going Live

Once the assistant answers well in testing, put it in front of customers:

* **Website widget** -- add one script tag to your site. See [Widget Installation](/widget/installation).
* **Messaging channels** -- connect WhatsApp, Messenger, Instagram, SMS, or email. See [Channels](/features/channels).
* **Universal Inbox** -- watch conversations arrive and take over from the AI whenever a human should answer. See [Inbox](/features/inbox).

## Key Concepts

Before diving deeper, here are the core concepts you will encounter throughout IllumiChat:

| Concept             | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| **Workspaces**      | Separate environments for organizing members, assistants, and conversations                               |
| **Assistants**      | Custom AI personas configured with specific instructions and knowledge sources                            |
| **Knowledge Base**  | The content an assistant searches to answer accurately — files, websites, text, Q\&A, and live store data |
| **Channels**        | Where an assistant is reachable: website widget, WhatsApp, Messenger, Instagram, SMS, email               |
| **Universal Inbox** | One shared queue for every channel, where your team can take over from the AI                             |

## Next Steps

<CardGroup>
  <Card title="Assistants" icon="robot" href="/features/assistants">
    Configure instructions, knowledge, visibility, and handoff behavior.
  </Card>

  <Card title="Knowledge Base" icon="book" href="/features/knowledge-base">
    Add files, websites, Q\&A, and live store data for grounded answers.
  </Card>

  <Card title="Workspaces" icon="building" href="/features/workspaces">
    Set up workspaces, invite team members, and manage roles.
  </Card>

  <Card title="Account Settings" icon="gear" href="/account">
    Manage your profile, preferences, and billing.
  </Card>
</CardGroup>


# Configuration
Source: https://docs.illumichat.com/widget/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'
}
```

## Forms

Forms collect structured information from a visitor inside the conversation. Each assistant has two, edited on its **Forms** page:

* **Lead Capture** -- name, email, phone and anything else you want from a prospect
* **Support Tickets** -- the details a ticket needs before it's created (see [Tickets](/features/tickets))

Both use the same builder. Open your assistant, go to **Forms**, pick the tab, and turn the form on with **Enable Form**.

### Building the form

Each form has its own heading, description, button text and success message -- leave any of them blank to fall back to the default copy. Below that, add up to **20 fields**, drag to reorder, and click a field to open its settings.

### Field types

| Type             | What the visitor sees                     | Notes                                                   |
| ---------------- | ----------------------------------------- | ------------------------------------------------------- |
| Single-line text | A one-line input                          | Accepts an accepted-format rule                         |
| Multi-line text  | A resizable text area                     | For longer answers; accepts an accepted-format rule     |
| Email            | A one-line input                          | Validated as an email address automatically             |
| Phone            | A country-code picker plus a number input | Validated as a phone number automatically               |
| Dropdown         | A list of choices you define              | Can route its answer to a reportable field              |
| Checkbox         | A single tick-box                         | Optional unless you mark it required                    |
| Consent          | A single tick-box                         | Always required -- use it for terms and privacy opt-ins |

<Note>
  Single-line and multi-line differ only in the input that renders, not in how much text they accept. There is no character limit to set: every answer is accepted up to the platform's 10,000-character cap, which applies whatever the form is configured to do.
</Note>

### Field settings

| Setting         | Applies to                      | What it does                                                                                                                                                                                                |
| --------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Required        | All except Consent              | Blocks submission until the field has an answer. Consent is always required.                                                                                                                                |
| Label           | All                             | The field's name, and the name the answer appears under in your submissions                                                                                                                                 |
| Placeholder     | All except tick-boxes           | Faint example text that vanishes as the visitor types                                                                                                                                                       |
| Description     | All                             | Guidance under the field that stays visible while they type. URLs become links -- the right home for consent wording.                                                                                       |
| Accepted format | Single-line and multi-line text | Restricts which characters are allowed -- Any text, Letters only, Letters and numbers, or Numbers only -- without writing a regular expression                                                              |
| Error Message   | Text, email and phone           | Replaces the wording shown when an answer breaks a rule. Leave blank and each rule supplies its own.                                                                                                        |
| Options         | Dropdown                        | The choices. **Label** is what the visitor reads; **Value** is what's stored and exported -- keep Value stable once submissions exist.                                                                      |
| Save answer to  | Dropdown                        | Routes the answer into **Lead interest** or **Ticket issue type** so you can filter and group by it, instead of leaving it in the submission data. Use **Fill from catalog** to set matching option values. |

### When the form appears

**When to Show Form** offers four rules:

* **Before first message** -- as soon as the widget opens
* **After messages** -- once the visitor has sent a set number (1--100)
* **After delay** -- once the widget has been open for a set time (1--600 seconds)
* **Manual trigger only** -- only when your own code asks for it

Separately, the **AI trigger prompt** tells the assistant when to offer the form mid-conversation. Leave it blank and the AI decides for itself -- it offers the lead form when someone asks about pricing, requests a demo or wants to be contacted, and a ticket when someone reports a bug or asks to escalate.

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


# Installation
Source: https://docs.illumichat.com/widget/installation

Add the IllumiChat widget to your website

## Quick Start

Add the following script tag to your HTML, just before the closing `</body>` tag:

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="YOUR_ASSISTANT_ID"
  async
></script>
```

Replace `YOUR_ASSISTANT_ID` with the assistant ID from your IllumiChat dashboard (**Settings > Widget** on the assistant page).

## Framework Guides

<CodeGroup>
  ```html Plain HTML theme={null}
  <!DOCTYPE html>
  <html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <!-- Your page content -->

    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="YOUR_ASSISTANT_ID"
      async
    ></script>
  </body>
  </html>
  ```

  ```tsx React / Next.js theme={null}
  // components/IllumiChatWidget.tsx
  'use client';

  import Script from 'next/script';

  export function IllumiChatWidget() {
    return (
      <Script
        src="https://widget.illumichat.com/v1/widget.js"
        data-assistant-id="YOUR_ASSISTANT_ID"
        strategy="lazyOnload"
      />
    );
  }

  // Then in your layout:
  // import { IllumiChatWidget } from '@/components/IllumiChatWidget';
  // <IllumiChatWidget />
  ```

  ```php WordPress theme={null}
  <!-- Add to your theme's footer.php, before </body> -->
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="YOUR_ASSISTANT_ID"
    async
  ></script>
  ```

  ```vue Vue.js theme={null}
  <template>
    <div id="app">
      <!-- Your app content -->
    </div>
  </template>

  <script>
  export default {
    mounted() {
      if (!document.getElementById('illumichat-widget')) {
        const script = document.createElement('script');
        script.id = 'illumichat-widget';
        script.src = 'https://widget.illumichat.com/v1/widget.js';
        script.async = true;
        script.dataset.assistantId = 'YOUR_ASSISTANT_ID';
        document.body.appendChild(script);
      }
    },
    beforeUnmount() {
      const el = document.getElementById('illumichat-widget');
      if (el) el.remove();
    }
  };
  </script>
  ```
</CodeGroup>

## Local Development

When developing locally, point the script at your local dev server:

```html theme={null}
<script
  src="http://localhost:3000/v1/widget.js"
  data-assistant-id="YOUR_ASSISTANT_ID"
  async
></script>
```

<Note>
  The local widget script is served from the Next.js dev server. Make sure you have run `pnpm dev` before loading the page.
</Note>

## Domain Restrictions

For security, widgets can be restricted to load only on specific domains. If domain restrictions are enabled and your domain is not on the list, the widget will not render.

**To configure allowed domains:**

1. Open your assistant's **Settings** page
2. Go to the **Widget** tab
3. Under **Allowed Domains**, add each domain where the widget should work
4. Save your changes

<Warning>
  If you use domain restrictions, add **both** `www.example.com` and `example.com` if your site is accessible at both addresses. Also add `localhost` for local development.
</Warning>

## Verifying the Installation

After adding the script tag:

1. Open your page in a browser
2. Look for the chat bubble in the bottom-right corner
3. Click it to open the chat panel
4. Send a test message to confirm the assistant responds

If the widget does not appear, open your browser's developer console (F12) and check for error messages. Common issues include an incorrect assistant ID, domain restrictions, or a network error loading the script.

## Next Steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/widget/configuration">
    Customize the widget's appearance, behavior, and authentication.
  </Card>

  <Card title="SDK Reference" icon="brackets-curly" href="/widget/sdk-reference">
    Use the JavaScript API to control the widget programmatically.
  </Card>
</CardGroup>


# Widget Overview
Source: https://docs.illumichat.com/widget/overview

Embed AI-powered chat on your website

The IllumiChat Widget lets you embed an AI-powered chat interface on any website. Visitors can interact with your custom assistants directly from your site -- no login required.

## Use Cases

<CardGroup>
  <Card title="Customer Support" icon="headset">
    Let visitors ask questions and get instant AI-powered answers 24/7.
  </Card>

  <Card title="Lead Generation" icon="user-plus">
    Capture visitor information through the built-in lead form and feed it into your contacts.
  </Card>

  <Card title="Documentation Help" icon="book">
    Connect your docs as knowledge so visitors can search and get answers from your content.
  </Card>

  <Card title="Internal Tools" icon="building">
    Use authenticated mode for internal portals where employees interact with company assistants.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Create an assistant">
    Set up an assistant with custom instructions and connect it to your knowledge base.
  </Step>

  <Step title="Add the widget script">
    Drop a single script tag into your website's HTML.
  </Step>

  <Step title="Visitors start chatting">
    A chat bubble appears on your site. Visitors click it to open the chat panel and interact with your assistant.
  </Step>
</Steps>

## Key Features

* **Zero-code installation** -- A single script tag is all you need
* **Customizable appearance** -- Match your brand colors, position, and theme
* **Multiple auth modes** -- Anonymous, authenticated (Auth0), or auto-detect
* **Lead capture** -- Collect visitor information before or during conversations
* **Session persistence** -- Conversations persist across page navigations
* **Domain restrictions** -- Control which domains can load the widget
* **Programmatic API** -- Open, close, send messages, and listen to events from JavaScript
* **Mobile responsive** -- Works on all screen sizes

## Quick Start

Add this script tag to your HTML, replacing `YOUR_ASSISTANT_ID` with your assistant's ID:

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="YOUR_ASSISTANT_ID"
  async
></script>
```

<Tip>
  Find your assistant ID in the assistant's **Settings > Widget** tab in the IllumiChat dashboard.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Installation" icon="code" href="/widget/installation">
    Framework-specific installation guides for React, Next.js, WordPress, and more.
  </Card>

  <Card title="Configuration" icon="sliders" href="/widget/configuration">
    Customize appearance, behavior, authentication, and lead capture.
  </Card>

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


# SDK Reference
Source: https://docs.illumichat.com/widget/sdk-reference

JavaScript API for programmatic widget control

The IllumiChat Widget SDK provides a JavaScript API for creating, controlling, and responding to widget events programmatically.

<Note>
  The SDK always opens the production AI-first widget. There is no public
  version selector or conversation-start mode. Existing embed URLs and SDK
  initialization calls continue to work with the production renderer.
</Note>

## Global API

### IllumiChat.Widget

The main widget class. Create an instance by passing a configuration object.

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

```javascript theme={null}
const widget = IllumiChat.getInstance();
widget.open();
```

<Note>
  `getInstance()` returns `null` if no widget has been initialized yet.
</Note>

### IllumiChat.destroyInstance()

Destroys the current singleton instance, removes the widget from the DOM, and cleans up all event listeners.

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

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

<Warning>
  You must call `initialize()` before calling any other method. Calling `open()` or `sendMessage()` on an uninitialized widget has no effect.
</Warning>

### open()

Opens the chat panel.

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

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

## Widget States

| 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

```javascript theme={null}
// Subscribe
const unsubscribe = widget.on('open', () => {
  console.log('Chat panel was opened');
});

// Unsubscribe
unsubscribe();
```

### One-Time Listeners

```javascript theme={null}
widget.once('ready', () => {
  console.log('Widget is ready — fires only once');
});
```

### Removing a Specific Handler

```javascript theme={null}
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`                  | `{ message, code? }`                                             | An error occurred                                                  |
| `message:sent`           | `{ content, timestamp }`                                         | The visitor sent a message                                         |
| `message:received`       | `{ content, timestamp }`                                         | The assistant sent a response                                      |
| `conversation:started`   | `{ conversationId }`                                             | A new conversation was initiated                                   |
| `session:created`        | `{ sessionId, visitorId }`                                       | A new session was created                                          |
| `session:restored`       | `{ sessionId, visitorId }`                                       | An existing session was restored                                   |
| `lead:submitted`         | `{ contactId, isNew }`                                           | The lead plugin submitted a contact                                |
| `form:submitted`         | `{ formId, data }`                                               | The active lead, ticket, or custom form was submitted successfully |
| `form:error`             | `{ error }`                                                      | The active form submission failed with a visitor-safe error        |
| `form:hide`              | --                                                               | The active form was closed                                         |
| `live_chat:started`      | `{ sessionId, agentName, agentId }`                              | A live-support session was assigned                                |
| `live_chat:message`      | `{ sessionId, content, senderType, senderName?, senderAvatar? }` | A live-support message was delivered                               |
| `live_chat:queue_update` | `{ sessionId, position }`                                        | The visitor's queue position changed                               |
| `live_chat:ended`        | `{ sessionId, endedBy }`                                         | The live-support session ended                                     |

### Event Examples

**Track conversations in analytics:**

```javascript theme={null}
widget.on('conversation:started', ({ conversationId }) => {
  analytics.track('Chat Started', { conversationId });
});

widget.on('message:sent', ({ content }) => {
  analytics.track('Chat Message Sent', { content });
});
```

**Capture leads and forward to a CRM:**

```javascript theme={null}
widget.on('lead:submitted', ({ contactId, isNew }) => {
  analytics.track('Lead Captured', { contactId, isNew });
});
```

**Handle errors:**

```javascript theme={null}
widget.on('error', ({ message, code }) => {
  console.error('Widget error:', code, message);
  document.getElementById('fallback-support').style.display = 'block';
});
```

**Observe forms and live support:**

```javascript theme={null}
widget.on('form:submitted', ({ formId, data }) => {
  analytics.track('Widget Form Submitted', { formId, fieldCount: Object.keys(data).length });
});

widget.on('live_chat:started', ({ sessionId, agentName }) => {
  analytics.track('Live Support Started', { sessionId, agentName });
});
```

## Production capability notes

* Text messages, forms, quick-reply actions, and live-support lifecycle events
  are supported by the production v2 experience.
* Attachments and browser voice input are fast-follow composer capabilities.
  Do not use SDK configuration to infer that those controls are visible.
* The plugin registration API remains available for compatibility and host-side
  lifecycle integrations. Plugin-rendered widget UI is a fast-follow v2
  capability and should not be treated as generally available.

## Configuration Reference

```typescript theme={null}
interface WidgetConfig {
  assistantId: string;
  position?: 'bottom-right' | 'bottom-left';
  authMode?: 'anonymous' | 'authenticated' | 'auto';
  branding?: {
    primaryColor?: string;    // Default: "#6366f1"
    companyName?: string;
    launcherSize?: number;    // Default: 60
  };
  autoOpen?: number;          // Delay in ms, 0 to disable
  suggestedMessages?: string[];
  popupMessages?: string[];   // Teaser bubbles above the launcher
  suggestedMessagesBubbles?: {
    enabled?: boolean;        // Default: false (dashboard toggle overrides)
    delay?: number;           // Default: 3000
  };
  metadata?: Record<string, string | number | boolean>;
  session?: {
    persist?: boolean;        // Default: true
  };
  debug?: boolean;            // Default: false
}
```

## TypeScript Declarations

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


# Widget Experience
Source: https://docs.illumichat.com/widget/widget-v2

The production AI-first widget, including forms, live support handoff, history, and recovery

<Note>
  The production widget uses the v2 experience and starts every conversation
  with the AI assistant. Existing embed snippets, sessions, public endpoints,
  and assistant IDs continue to work without a version parameter or migration.
</Note>

The widget gives visitors an immediate AI answer and can move the conversation
to a person when live support is appropriate. It keeps the same iframe-based
security boundary and JavaScript SDK used by existing installations.

## Production capabilities

| Capability                         | Description                                                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **AI-first conversations**         | Every conversation starts with the configured AI assistant. Visitors can request a person, and assistant tools can request a handoff when appropriate. |
| **Quick replies**                  | Tappable actions can send a message, open a configured form, or request live support.                                                                  |
| **Lead, ticket, and custom forms** | Assistant tools and the SDK can open accessible forms without leaving the conversation. Failed submissions keep the visitor's entered values.          |
| **Transparent handoff**            | When live support is available, visitors see queue and assignment updates and continue in the same transcript with the assigned agent.                 |
| **Conversation recovery**          | Persisted history, new/clear controls, delivery errors, and retry actions help visitors recover without losing accepted messages or partial responses. |
| **Feedback and CSAT**              | Message feedback and post-handoff satisfaction prompts appear when enabled for the assistant.                                                          |
| **Responsive, accessible UI**      | The launcher and panel adapt to mobile viewports, honor reduced motion, preserve keyboard focus, and expose named controls and status announcements.   |
| **Server-enforced branding**       | Colors, launcher size, avatar, dimensions, and powered-by entitlement come from the public widget configuration.                                       |

## Configure the widget

Open **Assistant → Widget** (`/assistants/[id]/widget`) to configure the
production experience. The available settings include:

* appearance, launcher, avatar, dimensions, and branding;
* welcome copy, suggested messages, and quick replies;
* history, feedback, live-support status, and response-time labels;
* lead and ticket forms; and
* audience rollout rules on the assistant's **Embed** page.

The conversation itself remains AI-first. You do not need to choose a widget
version or a conversation-start mode in the embed code or SDK.

## Forms and live support

The assistant can display the enabled lead or ticket form during a conversation.
An SDK caller can also supply a complete custom form with a stable ID. Form
success, error, and close events are delivered to the host page only after the
matching outcome.

When a visitor requests a person, the widget checks live-support availability
and any required contact fields before entering the queue. If live support is
unavailable or a handoff fails, the visitor stays in the AI conversation and
receives a retryable, visitor-safe status.

## Audience rollout

Audience rollout controls whether the launcher appears for everyone, on
specific URL paths, or only through a secret test link. It does not select a
widget version and it does not allocate traffic by percentage. See
[Configuration](/widget/configuration#rollout) for the audience controls.

## Fast-follow capabilities

Attachments, browser voice input, and plugin-rendered widget UI are fast-follow
capabilities. They are not part of the production v2 composer today, even if a
legacy configuration field or SDK plugin API is still present. Plan your
visitor experience around text messages, forms, and live support until these
controls are announced as generally available.

## Operational fallback

IllumiChat operations can temporarily restore the classic renderer without an
embed or API change. This emergency fallback preserves stored assistant
configuration and conversation data while an incident is investigated; it is
not a merchant-facing version setting.

## Next steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/widget/configuration">
    Configure appearance, authentication, forms, and audience rollout.
  </Card>

  <Card title="SDK Reference" icon="brackets-curly" href="/widget/sdk-reference">
    Control the widget and subscribe to message, form, and live-chat events.
  </Card>
</CardGroup>