Complete reference of all widget configuration properties, types, defaults, and API validation bounds.
Where settings are edited
WebChat AIPATCH /api/websites/{id}/widget.| Option | Type | Default | Description |
|---|---|---|---|
| theme | 'light' | 'dark' | 'auto' | 'light' | Base color mode. "auto" follows the visitor's operating system prefers-color-scheme. |
| theme_preset | preset id | '' (classic) | Curated palette preset id (11 options available). Empty string uses the custom classic palette. |
| primary_color | #rrggbb (hex) | #10A37F | Primary action color for the launcher icon, header, and send button. |
| accent_color | #rrggbb (hex) | #25D366 | Secondary accent color for badges and highlights. |
| font_size | 'sm' | 'md' | 'lg' | 'md' | Base font size inside the chat window (14px, 16px, or 18px). |
| dark_mode | boolean | false | Force dark theme mode regardless of the visitor system setting. |
| font_family | string | null | null | Font family stack. Null uses system default. Accepts any of the 10 curated typography options. |
| Option | Type | Default | Description |
|---|---|---|---|
| bot_name | string (max 60) | 'AI Assistant' | Assistant name displayed in the top header and message bubbles. |
| bot_status_text | string (max 40) | 'Online' | Presence indicator line under the bot name. |
| logo_url | https://... | null | null | Brand logo displayed in the widget header. |
| avatar_url | https://... | null | null | Image avatar URL displayed next to bot messages. |
| header_color | #rrggbb | null | null | Custom header background color; null uses the theme preset default. |
| secondary_color | #rrggbb | null | null | Secondary gradient color; null uses accent color. |
| background_color | #rrggbb | null | null | Chat window surface color; null uses theme default. |
| text_color | #rrggbb | null | null | Primary text color; null uses theme default. |
| Option | Type | Default | Description |
|---|---|---|---|
| position | 'bottom-right' | 'bottom-left' | 'bottom-right' | Corner of the browser viewport where the launcher sits. |
| welcome_message | string (max 500) | 'Hi! How can I help you today?' | Greeting message displayed above the first visitor turn. |
| placeholder | string (max 120) | 'Type your message...' | Input composer placeholder text. |
| suggested_questions | string[] (max 5) | [] | Quick-prompt suggestion chips offered to new visitors (max 200 chars each). |
| branding | boolean | true | Display the "Powered by WebChat AI" attribution link in the footer. |
| auto_open | boolean | false | Automatically open the chat window when a new visitor lands on the page. |
| enabled | boolean | true | Master toggle. When false, the widget does not render on host pages. |
| Option | Type | Default | Description |
|---|---|---|---|
| width | CSS length (max 20) | '400px' | Chat window width (supports px, rem, vw). Enforces responsive mobile constraints. |
| height | CSS length (max 20) | '640px' | Chat window height (supports px, rem, vh). |
| border_radius | CSS length (max 20) | '16px' | Corner radius for the chat window container. |
| launcher_size | CSS length (max 20) | '56px' | Diameter of the floating launcher action button. |
| Option | Type | Default | Description |
|---|---|---|---|
| allowed_domains | string[] (max 50) | auto-seeded | Hostnames permitted to embed this widget (e.g. "example.com", "*.example.com"). Unlisted origins receive 403. |
Curated color palettes bundling header, surface, bubble, and text tokens.
On-demand curated font families loaded securely via Google Fonts.
Constraints enforced by the REST API.
bot_name: String between 1 and 60 characters.bot_status_text: String up to 40 characters.welcome_message: String up to 500 characters.placeholder: String up to 120 characters.suggested_questions: Array of up to 5 items; each question max 200 characters.allowed_domains: Array of up to 50 hostname patterns.logo_url and avatar_url: HTTPS URLs up to 2048 characters.width, height, border_radius, launcher_size: Valid CSS lengths up to 20 characters.Related documentation
Ready to build?
Register a website and get a live assistant in minutes.