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

# Widget Experience

> 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 cols={2}>
  <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>