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

# Web widgets overview

> Embed an Anyreach agent as a chat and voice bubble on your website.

A web widget embeds one of your Anyreach agents as a chat-and-voice bubble on your website. End users open the bubble and talk to the agent by text or by voice, in the same widget, without leaving your page.

Each widget is a saved record that binds an agent to a published version, scopes it to a set of allowed domains, and carries a configuration object for appearance, branding, quick actions, forms, and feedback.

## What a widget binds together

A widget record holds these fields:

| Field              | Type      | Default    | Description                                                                     |
| ------------------ | --------- | ---------- | ------------------------------------------------------------------------------- |
| `id`               | UUID      | generated  | Widget identifier. Used in the embed snippet and in public endpoints.           |
| `organization_id`  | string    | from token | The organization that owns the widget. Set from your auth token at creation.    |
| `agent_id`         | UUID      | required   | The agent the widget serves.                                                    |
| `agent_version_id` | UUID      | required   | The specific agent version end users talk to. Pin this to a published version.  |
| `domains`          | `text[]`  | `[]`       | Allowed domains the widget may load on.                                         |
| `published`        | boolean   | `false`    | Whether the widget is live. Must be `true` for the widget to serve.             |
| `config`           | object    | `{}`       | Appearance, branding, quick actions, forms, and feedback, versioned under `v1`. |
| `created_at`       | timestamp | now        | When the widget was created.                                                    |
| `updated_at`       | timestamp | now        | When the widget was last changed.                                               |

The `config` object is namespaced under a `v1` key so its shape can evolve without breaking existing embeds. Appearance, text and voice options, quick actions, forms, and feedback all live inside `config.v1`.

## Requirements to go live

Two gates must both be satisfied before a widget serves traffic:

<Steps>
  <Step title="The agent has a published version">
    The widget's `agent_version_id` should point at a published version of the agent. Publish the agent version you want end users to reach before pointing a widget at it.
  </Step>

  <Step title="The widget itself is published">
    The widget's own `published` flag must be `true`. A widget with `published` set to `false` exists but does not go live.
  </Step>
</Steps>

<Note>
  Pinning the widget to a specific `agent_version_id` means published changes to other versions do not silently alter what end users experience. Update the widget's version when you want to roll a new version out.
</Note>

## How conversations work

End users talk to the agent over LiveKit WebRTC. The same widget handles both text chat and voice on the `webrtc` channel, so switching between typing and speaking happens inside one session.

```text theme={null}
Browser page
   |
   |  loads embed snippet (gated by allowed domains)
   v
Web widget  ──binds──>  agent + published agent version
   |
   |  opens a conversation over LiveKit WebRTC
   v
Agent  <── text and voice in the same session ──>  End user
```

When an end user opens a conversation, the widget creates it on the `webrtc` channel and joins a LiveKit room. The widget can resume an existing conversation by id, reconnecting the user to the agent in a fresh room.

## Allowed domains and security

The `domains` list is the allowlist of sites the widget may run on. The public embed snippet reads a widget's allowed domains and enforces them, so a widget cannot be loaded from a site you have not listed. Keep this list tight and add only the origins you control.

## Next steps

<CardGroup cols={2}>
  <Card title="Create a widget" icon="plus" href="/web-widgets/creating-a-widget">
    Bind an agent and published version, set allowed domains, and publish.
  </Card>

  <Card title="Install the snippet" icon="code" href="/web-widgets/installing-the-snippet">
    Drop the embed snippet onto your site and verify it loads.
  </Card>

  <Card title="Appearance and branding" icon="palette" href="/web-widgets/appearance-and-branding">
    Theme the bubble, set avatars, and apply your brand.
  </Card>

  <Card title="Text, voice, and quick actions" icon="comments" href="/web-widgets/text-voice-and-quick-actions">
    Tune chat and voice behavior and suggested questions.
  </Card>

  <Card title="Forms and feedback" icon="clipboard" href="/web-widgets/forms-and-feedback">
    Collect input mid-conversation and gather post-conversation feedback.
  </Card>

  <Card title="Allowed domains and security" icon="shield" href="/web-widgets/allowed-domains-and-security">
    Lock the widget to the domains you control.
  </Card>
</CardGroup>