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

# Creating a widget

> Create a widget from the Widgets section or an agent Deploy section.

A web widget is an embeddable chat and voice surface backed by one published agent version. You create it once, configure it in the Widget Builder, and drop a single script tag on your site. This page covers creating a widget and the three Widget Builder tabs.

## Create a widget

A widget always points at a specific assistant and a specific published version. You can create one from either place:

<Tabs>
  <Tab title="From the Widgets section">
    1. Open **Widgets** from the sidebar (`/widgets`).
    2. Click **Create Widget**.
    3. Pick an **Agent**. Agents with no published version are disabled and labeled *(agent not published)*.
    4. Pick an **Agent Version**. Only published versions are listed.
    5. Click **Create**.

    The new widget starts **Not published**. Click the row to open the Widget Builder.
  </Tab>

  <Tab title="From an agent Deploy section">
    Open the agent, go to its deployment step, and turn on the web widget channel. This creates a widget for that agent and opens the same Widget Builder inline, so you can configure and publish it without leaving the agent.
  </Tab>
</Tabs>

<Note>
  You need the `web_widgets:manage` scope to create or edit a widget. `web_widgets:read` grants view-only access.
</Note>

## Widget Builder

Opening a widget shows the **Widget Builder**: a configuration panel on the left and a live preview on the right. The panel has three tabs.

| Tab         | What it controls                                                                                                 |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| **General** | Assistant assignment, name, privacy policy, allowed domains, branding, prompts, forms, and publish state         |
| **Theming** | Colors, theme mode, and trigger appearance — see [Appearance and branding](/web-widgets/appearance-and-branding) |
| **Deploy**  | The embed snippet for your platform — see [Installing the snippet](/web-widgets/installing-the-snippet)          |

### General

The General tab holds the widget's core settings.

| Field                          | Type   | Default        | Description                                                                                       |
| ------------------------------ | ------ | -------------- | ------------------------------------------------------------------------------------------------- |
| **Assistant**                  | Select | —              | The agent this widget serves.                                                                     |
| **Assistant version**          | Select | —              | A published version of that agent. Only published versions appear.                                |
| **Name**                       | Text   | Assistant name | Display name shown in the chat header. Defaults to the selected assistant's name when left empty. |
| **Privacy Policy URL**         | URL    | empty          | Link shown at the bottom of the chat interface.                                                   |
| **Allowed Domains**            | List   | empty          | Domains that may embed this widget.                                                               |
| **Hide "Powered by Anyreach"** | Toggle | off            | Removes the Anyreach attribution from the widget.                                                 |
| **Suggested Questions**        | List   | empty          | Up to 4 prompts shown above the chat button.                                                      |
| **Pre-Conversation Form**      | Toggle | off            | Collects user details before the conversation starts.                                             |
| **Post-Conversation Feedback** | Toggle | off            | Collects feedback at the end of a chat conversation (WebRTC only).                                |
| **Enabled**                    | Toggle | off            | Whether the widget renders where it is embedded.                                                  |

Click **Save changes** to persist the tab.

#### Allowed domains

Whitelist the domains that are allowed to embed this widget. Leave the list empty to allow all domains — intended for development only. When the list is empty, the widget can be embedded on any site.

#### Suggested questions

Add up to 4 pre-configured prompts that appear above the chat button to nudge visitors into starting a conversation. Use **Add question** to append one; the button disappears once you reach 4.

<Note>
  Suggested questions are not visible on mobile.
</Note>

#### Pre-conversation form

Turn on **Pre-Conversation Form** to show a form before the conversation begins. Enabling it seeds a default form with **Name**, **Email**, and an optional **Phone Number** field, which you can edit in the inline form editor. The **Only show once per user** toggle controls whether returning visitors see the form again; it is on by default.

#### Post-conversation feedback

Turn on **Post-Conversation Feedback** to collect feedback when a chat ends. Enabling it seeds a default form with a 1–5 star **Rating** and an optional **Comments** field, plus an editable **Thank-you message**.

<Warning>
  Post-conversation feedback applies to WebRTC chat conversations only.
</Warning>

#### Publishing

The **Enabled** toggle is the widget's publish switch. When enabled, the widget renders wherever it is embedded; when disabled, it will not render even if the snippet is present. New widgets start disabled.

### Theming

The Theming tab covers auto-branding, theme mode, and the colors and trigger styling that control how the widget looks. See [Appearance and branding](/web-widgets/appearance-and-branding) for the full reference.

### Deploy

The Deploy tab generates the embed snippet. Pick your platform to get a copy-ready script tag and platform-specific install instructions. See [Installing the snippet](/web-widgets/installing-the-snippet) for the step-by-step.

## How the config is stored

Every General and Theming setting is written to the widget's config under a versioned `v1` key:

```json theme={null}
{
  "v1": {
    "chat": {
      "name": "Support",
      "privacy_policy_url": "https://example.com/privacy",
      "disable_powered_by_anyreach": true
    },
    "trigger": { "suggestedQuestions": ["..."] },
    "pre_conversation_form": { "...": "..." },
    "post_conversation_feedback": { "...": "..." }
  }
}
```

Allowed domains and the publish state are stored on the widget record itself (`domains` and `published`), not inside `config.v1`.

## Next steps

<CardGroup cols={2}>
  <Card title="Appearance and branding" icon="palette" href="/web-widgets/appearance-and-branding">
    Theme the widget with colors, modes, and trigger styling.
  </Card>

  <Card title="Installing the snippet" icon="code" href="/web-widgets/installing-the-snippet">
    Get the embed snippet and add it to your site.
  </Card>
</CardGroup>