Chat widget

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

Field reference: widget — every field, type, default, and tier for this page.

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.

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

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:

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

Manage via the Management MCP

This page can be configured programmatically through the Management 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

Example:

{
  "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.