> ## 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. # widget > The embeddable chat widget design and behaviour — mode, branding, colours, launcher, sizing, pre-chat fields, conversation starters, and gating. Separate… # `widget` — Web-chat widget The embeddable chat widget design and behaviour — mode, branding, colours, launcher, sizing, pre-chat fields, conversation starters, and gating. Separate from the public page layout. **Section key** `widget` · **Shape** object · **Tier** Pro and up (free trial includes it)\ **Edit in the dashboard:** [Widgets page](/sidebar-menu/widgets)\ **Related:** [Embedding](/sidebar-menu/widgets) · [Chat link](/sidebar-menu/web) ## Fields | Field | Required | Type | Allowed values / constraints | Default | Description | | ----------------------- | -------- | --------------- | -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | no | boolean | — | — | Master on/off for the widget embed. | | `mode` | no | enum | one of `popup`, `popup-bare`, `inline`, `sidebar`, `fullscreen`, `ai-chat` | — | Display mode. | | `headerTitle` | no | string | — | — | Title shown in the widget header. | | `headerSubtitle` | no | string | — | — | Subtitle shown below the header title. | | `welcomeMessage` | no | string | — | — | First message the widget shows when opened. | | `placeholderText` | no | string | — | — | Placeholder text in the composer input. | | `avatarUrl` | no | string | — | — | URL for the agent avatar image. | | `showBranding` | no | boolean | — | — | 'Powered by Agentheya' badge. | | `suggestedMessages` | no | string | — | — | Newline-separated suggested messages shown before the first user message. | | `themeMode` | no | enum | one of `light`, `dark`, `auto` | — | Which colour scheme the widget renders in. 'light' / 'dark' force the light / dark scheme; 'auto' = 'web page default' — the loader detects the host page's colour scheme (class / data-theme attributes) and falls back to the visitor's OS prefers-color-scheme. | | `primaryColor` | no | string | — | — | Light scheme: hex colour for the widget accent (e.g. '#0d9488'). | | `bgColor` | no | string | — | — | Light scheme: background hex colour. | | `fgColor` | no | string | — | — | Light scheme: foreground/text hex colour. | | `primaryColorDark` | no | string | — | — | Dark scheme: hex colour for the widget accent. Used when the resolved theme is dark. | | `bgColorDark` | no | string | — | — | Dark scheme: background hex colour. | | `fgColorDark` | no | string | — | — | Dark scheme: foreground/text hex colour. | | `borderRadius` | no | integer | — | — | Border radius in pixels (0–32). | | `fontFamily` | no | enum | one of `system`, `sans`, `serif`, `mono` | — | Font stack for text in the widget: 'system' (platform default), 'sans' (sans-serif), 'serif' (Georgia, Times), or 'mono' (monospaced). Controls readability and brand presentation. | | `bubbleStyle` | no | enum | one of `rounded`, `square`, `speech` | — | Visual style of chat message bubbles: 'rounded' (soft corners), 'square' (sharp corners), or 'speech' (speech balloon tails). Affects conversation appearance. | | `launcherShape` | no | enum | one of `circle`, `pill`, `square` | — | Outline of the launcher button when mode uses a floating launcher: 'circle' (circular button), 'pill' (horizontal capsule with optional text label), or 'square' (rectangular button). | | `launcherLabel` | no | string | — | — | Text label shown on the launcher when launcherShape='pill' (max 40 chars). For other shapes, the text is hidden behind the icon; configurable via UI but ignored if shape is not pill. | | `launcherIcon` | no | enum | one of `chat`, `message`, `help`, `sparkles`, `custom` | — | Icon displayed on the launcher button: 'chat', 'message', 'help', 'sparkles' (built-in SVGs), or 'custom' (use launcherIconUrl). Defaults to 'chat' when not specified. | | `launcherIconUrl` | no | string | — | — | Custom launcher icon URL (when launcherIcon='custom'). | | `position` | no | enum | one of `bottom-right`, `bottom-left`, `top-right`, `top-left` | — | Widget position on the page. | | `offsetX` | no | integer | — | — | Horizontal offset in pixels from the edge (0–400). | | `offsetY` | no | integer | — | — | Vertical offset in pixels from the edge (0–400). | | `windowWidth` | no | integer | — | — | Widget window width in pixels (110–4000). | | `windowHeight` | no | integer | — | — | Widget window height in pixels (120–2000). | | `startOpen` | no | boolean | — | — | Open the widget automatically on page load. | | `aiChatComposerHeight` | no | integer | — | — | Composer textarea height in pixels (60–400). | | `autoOpenDelay` | no | integer | — | — | Seconds before auto-opening (0 = disabled, max 600). | | `greetingDelay` | no | integer | — | — | Seconds before showing the greeting bubble (0 = immediate). | | `prechatFields` | no | array of object | — | — | Fields to collect from the user before the first message. Item fields below. | | `conversationStarters` | no | array of object | — | — | Quick-reply chips shown to the user at the start of a conversation. Item fields below. | | `collectFirstMessage` | no | boolean | — | — | When true, the prechat form appears before the chat opens (the visitor types their first message after filling fields). When false, the form and chat coexist so the visitor can type immediately. | | `soundOnMessage` | no | boolean | — | — | When true, the browser plays an audio notification when the agent sends a reply. Improves UX for visitors who might miss a new message while not focused on the widget. | | `persistConversation` | no | boolean | — | — | Save the conversation in the browser between page reloads. | | `allowFileUploads` | no | boolean | — | — | When true, the widget displays a file attachment button in the composer so visitors can upload documents, images, or other files with their message. Gated on agent capability (currently unused). | | `allowedDomains` | no | string | — | — | Newline-separated list of domains allowed to embed the widget. Empty = any domain. | | `showOnMobile` | no | boolean | — | — | When true, the widget is displayed on mobile devices; when false, it is hidden via CSS on screens below a breakpoint. Controls widget visibility across device sizes. | | `budgetCapCredits` | no | integer | — | — | Widget-spend cap in credits (sum of credits\_deducted across widget chats for the current budgetPeriod window). 0 = no cap. Supersedes the legacy dailyCapCredits key. | | `budgetPeriod` | no | enum | one of `daily`, `weekly`, `monthly` | — | Window the budgetCapCredits cap is measured over: daily = UTC calendar day, weekly = Monday–Sunday (UTC), monthly = calendar month (UTC). On exceed, the widget auto-pauses until the end of that window. | | `disabledUntilTs` | no | integer | — | — | Unix timestamp (ms) until which the widget is disabled. Server-managed; clients can clear it (set to 0) but cannot extend it. | | `homepageHtml` | no | string | — | — | Owner-supplied HTML rendered (sanitized server-side) on the widget's Home tab, below the agent description. Only surfaces in modes that have a Home tab (not ai-chat). | | `showStartersPreLaunch` | no | boolean | — | — | When true, conversation-starter chips are shown beside the launcher before the widget is opened. | ### `prechatFields` items Fields to collect from the user before the first message. | Field | Required | Type | Allowed values / constraints | Default | Description | | ------------- | -------- | ------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | no | string | — | — | Unique identifier (snake\_case, 32 chars max) for this form field. Used as the variable name when the value is passed to the LLM and the endpoint. Auto-slugified from label if missing. | | `label` | no | string | — | — | Human-readable label shown on the form (max 200 chars). Displayed above or next to the input; visitor-facing so should be clear and concise. | | `type` | no | enum | one of `text`, `email`, `textarea` | — | Input field type: 'text' (single-line input), 'email' (validated email address), or 'textarea' (multi-line text). Determines validation and rendering in the prechat form. | | `description` | no | string | — | — | Optional explanation (max 200 chars) for the field. Passed to the LLM in the visitor context block so the agent understands what the value represents; not shown to the visitor. | | `required` | no | boolean | — | — | When true, the visitor must fill this field before the chat unlocks. The form validates required fields before sending; optional fields may be left blank. | ### `conversationStarters` items Quick-reply chips shown to the user at the start of a conversation. | Field | Required | Type | Allowed values / constraints | Default | Description | | --------- | -------- | ------ | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `label` | no | string | — | — | Short label (max 80 chars) displayed on the quick-reply pill button. Should be a concise prompt (e.g. 'Pricing', 'Track order') that tells the visitor what the starter will ask. | | `message` | no | string | — | — | Full message text sent to the agent when the visitor clicks the starter pill (max 5000 chars). Treated as if the visitor typed it; can be a question, statement, or multi-sentence prompt. |