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
Related: Embedding · Chat link

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.