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

# Chat widget

> Embed your agent on any website — one script tag, no build step.

<Info>
  **Field reference:** [`widget`](/reference/widget) — every field, type, default, and tier for this page.
</Info>

The widget is an embeddable chat surface you add to any website. Depending on the display mode you pick it can appear as a floating launcher that opens a chat panel, an inline frame inside the page, a sidebar, a fullscreen takeover, or a bottom-anchored ai-chat composer.

## Getting the snippet

1. Open your agent and go to **Widget** in the sidebar.
2. Configure the widget (see options below).
3. Click **Copy snippet** and paste the `<script>` tag into your HTML, before the closing `</body>` tag.

```html theme={null}
<script
  src="https://agentheya.com/widget/{agent_name}.js"
  data-mode="popup"
  data-position="bottom-right"
  data-theme="auto"
  data-primary-color="#e65a1f"
></script>
```

Most settings (welcome message, theme colors, branding, pre-chat fields, etc.) are pulled live from your config when the script loads, so you don't need to re-copy the snippet after every change. Do re-copy after editing the `data-` attributes shown above (mode, position, theme, primary color).

## Display modes

The widget supports several display modes — pick one to match how you want it to appear on the page:

| Mode         | Description                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `popup`      | Floating launcher (bubble or pill) that opens a chat panel. Most common.                              |
| `popup-bare` | Same as `popup` but the launcher is rendered without its default chrome — you supply your own button. |
| `inline`     | Renders the chat inline at the script's location, no launcher.                                        |
| `sidebar`    | Docks the chat to one edge of the viewport.                                                           |
| `fullscreen` | Takes over the entire viewport.                                                                       |
| `ai-chat`    | Bottom-anchored floating composer that expands to a full chat panel after the first message.          |

## Position, size, theme

| Option                    | Values                                                 | Default          |
| ------------------------- | ------------------------------------------------------ | ---------------- |
| **Position**              | `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right`   |
| **Theme**                 | `light`, `dark`, `auto`                                | `auto`           |
| **Primary color**         | Any hex color                                          | Platform default |
| **Window width / height** | 110 – 4000 px / 120 – 2000 px                          | 340 × 460        |
| **Font**                  | `system`, `sans`, `serif`, `mono`                      | `system`         |
| **Message bubble style**  | `rounded`, `square`, `speech`                          | `rounded`        |

`auto` theme follows the visitor's operating system preference.

## Colors

The widget carries a full **light** palette and a matching **dark** palette — three hex values each — set with the swatch + hex inputs under **Appearance** on the Widget page (a **Light scheme** row and a **Dark scheme** row):

| Field                    | Scheme | Applies to                      |
| ------------------------ | ------ | ------------------------------- |
| **Primary color**        | Light  | Launcher, buttons, and accents. |
| **Background**           | Light  | Chat panel background.          |
| **Text color**           | Light  | Message and UI text.            |
| **Primary color** (dark) | Dark   | Accent color in dark mode.      |
| **Background** (dark)    | Dark   | Panel background in dark mode.  |
| **Text color** (dark)    | Dark   | Text in dark mode.              |

The dark trio applies whenever the resolved theme is dark — the visitor picks **Dark scheme**, or **Theme** is `auto` and their operating system is in dark mode. Leave any field blank to inherit a sensible platform default. Only **Primary color** is also written into the copy-paste snippet (`data-primary-color`); the rest load live from your config, so editing them needs no re-copy.

**Simple — just set your brand color.** Set **Primary color** to your brand hex (e.g. `#6d28d9`) and leave Background / Text and the dark-mode colors unset — the widget inherits sensible defaults in both light and dark.

### Dark mode theming

Set the light values — **Primary** `#6d28d9`, **Background** `#ffffff`, **Text** `#111111` — then the dark triad — **Primary (dark)** `#a78bfa`, **Background (dark)** `#111827`, **Text (dark)** `#f3f4f6`. With **Theme** set to `auto`, visitors on a dark-OS get the dark palette automatically instead of a jarring light bubble on a dark page.

## Launcher

For modes that use a launcher (`popup`, `popup-bare`, `ai-chat`) you can customise:

* **Launcher shape** — `circle`, `pill`, or `square`.
* **Launcher icon** — built-in (`chat`, `message`, `help`, `sparkles`) or `custom` with your own image.

## Header, welcome, suggested messages

* **Header title** and **subtitle** — shown at the top of the chat panel (e.g. "Chat with us" / "We typically reply in a few minutes").
* **Welcome message** — the first message the agent shows when the panel opens.
* **Suggested messages** — one per line; rendered as quick-reply chips so visitors can start the conversation with a tap.
* **Input placeholder** — text shown in the composer before the visitor types.
* **Avatar URL** — image shown next to agent messages.
* **Show "Powered by Agentheya" branding** — toggle.

## Pre-chat form

You can collect information before the conversation starts. Add fields on the Widget page; each field has a key, label, type (`text`, `email`, or `textarea`), optional description, and an optional required flag. Up to 12 fields are supported.

The agent receives the visitor's pre-chat answers (along with your field labels and descriptions) as context, so it can address the visitor by name and tailor its first reply.

## Conversation starters

Add up to 10 **conversation starters** — labelled buttons (each with a label and the message it sends) shown to the visitor before they type. Clicking one sends that message. Turn on **Show starters before launch** to float them above the launcher button so visitors see them without opening the widget. Great for steering visitors toward the questions your agent answers best.

## Homepage

Give the widget an optional **homepage** — custom HTML shown as a "Home" tab alongside "Messages". Use it for a welcome panel, FAQ links, or a hero image. When set, a bottom nav bar appears so visitors can switch between your homepage and the chat.

## Daily budget

Set a **Daily spend cap (credits)** on the Widget page to limit how many credits the widget can spend per UTC day. Set `0` for no limit. The current day's spend (in credits) is shown next to the cap so you can see how close you are. When the cap is hit the widget auto-pauses until UTC midnight, and you receive an email. You can re-enable it early from the Widget page.

## Allowed domains

Restrict which domains may load the widget by listing them in **Allowed domains** (one per line, e.g. `example.com`, `app.example.com`). A leading dot (`.example.com`) matches all subdomains. Leave empty to allow any domain. The same allow-list governs the [embedded chat page](/sidebar-menu/widgets).

## iframe alternative

If you want the **full chat page** inline (file uploads, page-layout blocks, login) instead of the floating widget, embed it as an `<iframe>` with `?embed=1`:

```html theme={null}
<iframe
  src="https://agentheya.com/agent/{agent_name}?embed=1"
  width="100%"
  height="700"
  style="border: none; border-radius: 12px;"
  allow="clipboard-write"
></iframe>
```

`?embed=1` strips the page chrome and enables a postMessage protocol for auto-resize and theme sync. See [Embedding the chat page](/sidebar-menu/widgets) for the full protocol and the allowed-domains gate. Use the **widget** (above) for a launcher-style popup; use the **embed** for an inline full-page chat.

***

## Examples

**Hello world — drop-in support bubble.** Leave every default, set **Allowed domains** to your site, copy the snippet into your page footer. You now have a chat bubble bottom-right that opens your agent. Two minutes, zero configuration.

**Simple — branded and on-message.** Set the primary colour to your brand colour, header title to "Ask Acme", welcome message to "Hi! Questions about your order or our products?", and add three conversation starters: "Track my order", "Return policy", "Talk to a human". Visitors land on a widget that looks like yours and nudges them toward what the agent handles.

**Medium — qualified leads with a pre-chat form.** Add pre-chat fields: `name` (text, required), `email` (email, required), `company` (text, optional). The agent greets the visitor by name and already knows their email, so a "book a demo" conversation can capture the lead without re-asking. Set a **Daily spend cap** of, say, 500 credits so a traffic spike can't run up an unbounded bill.

**Complex — a gated, homepage-fronted product assistant.** Set mode to a windowed panel, add a **homepage** with a hero image and three FAQ links, turn on **Show starters before launch**, and restrict **Allowed domains** to `.acme.com` (all subdomains). Visitors see the homepage first, can jump to FAQs or start a chat from a starter, and the widget only loads on your own domains. Pair with [pre-chat fields](#pre-chat-form) so every conversation arrives with visitor context.

**System-pushing — inline full-page chat with theme sync.** For a logged-in area of your app where you want the *entire* chat experience (uploads, history, page-layout blocks) embedded inline rather than as a popup, use the `?embed=1` iframe and wire up the postMessage protocol so the chat follows your app's light/dark toggle and auto-resizes to its content. This turns the agent into a native-feeling panel inside your product. See [Embedding the chat page](/sidebar-menu/widgets).

## Manage via the Management MCP

This page can be configured programmatically through the [Management MCP](/manage-mcp) — useful for AI agents and CI pipelines.

|               |                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------- |
| Endpoint      | `https://manage.agentheya.com/mcp`                                                          |
| Tool          | `config.set`                                                                                |
| Section       | `widgets`                                                                                   |
| Schema (HTTP) | [`GET /api/manage-mcp/schema/widgets`](https://agentheya.com/api/manage-mcp/schema/widgets) |

Example:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "widgets",
  "data": { /* see schema for accepted fields */ }
}
```

Partial updates are supported — only the fields you include are changed. Call `config.get` to read the current values and `schema.get` (or the HTTP schema URL above) to see the full field list.