Widget Configuration

Read and update the website widget configuration via the API.

The widget is a chat interface that you embed on your website — it appears as a floating bubble in the corner of the page that visitors can click to open a conversation with your AI Agent. The widget is fully customizable: you control its colors, size, position, greeting messages, and behavior.

These settings also affect the embed, which is a full-page or inline version of the same chat interface that you can place directly into your webpage layout (as opposed to the floating bubble). Both the widget and embed share the same configuration for appearance, messaging, and behavior.

With these endpoints, you can programmatically customize how Quickchat AI appears on your website — match your brand colors, set up pre-chat forms to collect visitor information, configure typing indicators, enable voice input, and more. For setup instructions, see the Website channel guide.

Scope: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell
Python

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"],
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "launcher_label": "Ask AI",
  "launcher_draggable": false,
  "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "theme": "light",
  "widget_theme_custom": {
    "colors": {
      "background": "#ffffff",
      "header": "#ffffff",
      "header_text": "#030712",
      "accent": "#27272a",
      "accent_hover": "#374151",
      "accent_text": "#ffffff",
      "bubble": "#27272a",
      "bubble_text": "#ffffff",
      "ai_bubble_text": "#030712",
      "tertiary": "#afafb2",
      "link": null,
      "input_background": "#ffffff",
      "input_text": "#030712",
      "input_placeholder": "#9ca3af",
      "border": "#e5e7eb"
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" }
  }
}

Content & Messaging

Field	Description
`welcome_message` string	Primary welcome message displayed when widget opens (HTML). Dashboard: Website > Greeting
`welcome_message2` string	Secondary welcome message shown below the primary greeting
`header` string	Text displayed in the widget header bar. Dashboard: Website > Header
`subtitle` string	Subtitle text shown below the header. Dashboard: Website > Subtitle
`input_placeholder` string	Placeholder text in the message input field (e.g., “Type your message…”)
`conversation_starters` array of strings or null	Suggested opening prompts shown as clickable buttons when the widget opens. Up to 3 entries, each up to ~100 characters
`background_disclaimer_text` string or null	Disclaimer text shown at the bottom of the chat window

Appearance

Field	Description
`primary_color` string	Widget accent color as CSS rgb value (e.g., `"rgb(0, 122, 255)"`). Used for buttons, links, and user message bubbles
`header_color` string	Header background color as CSS rgb value
`header_text_color` boolean	Header text brightness. `true` = white/light text (for dark headers), `false` = dark text (for light headers). Note: despite the name, this is a boolean, not a color string
`size` string	Launcher size preset: `"small"`, `"medium"`, or `"large"` (shown in the dashboard as Small, Input Only, and Classic)
`location` string	Widget position on the page: `"top-left"`, `"top-right"`, `"bottom-left"`, or `"bottom-right"`
`launcher_label` string or null	Text on the small launcher button (`size: "small"`), max 25 characters. `null` uses the default (`"Ask AI"`); `""` shows an icon-only launcher
`launcher_draggable` boolean	Allow visitors to drag the launcher to a different position on the page
`window_height` integer	Widget height in pixels (400-1200)
`window_width` integer	Widget width in pixels (300-700)
`avatar_image` string or null	URL of the AI Agent Avatar, shown both in the chat header and as the floating bubble icon. Upload via PATCH as base64. `null` means the avatar was deleted and the widget shows no avatar
`bubble_icon_image` string or null	Deprecated. Always mirrors `avatar_image` — the bubble icon and the chat avatar are now one image (see AI Agent Avatar unification)
`default_avatar_image` string	Read-only. URL of the default AI Agent Avatar that `use_default_avatar` restores
`theme` string	Color theme mode: `"light"` or `"dark"` (fixed presets) or `"custom"` (applies the `widget_theme_custom` palette)
`widget_theme_custom` object	Custom palette applied when `theme` is `"custom"`. Contains `colors` (header, accent, message bubble, AI text, `link`, input, border, and more, as hex or `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` for bubbles, input, and buttons), and `font.size` (`"sm"`/`"base"`/`"lg"`). On PATCH, send the whole object — missing keys reset to defaults. `colors.link` defaults to `null`, meaning links inherit the surrounding text color

Behavior

Field	Description
`popup_active` boolean	Show a popup prompt near the widget bubble to encourage visitors to start a conversation
`window_auto_open` boolean	Automatically open the widget when the page loads (instead of showing just the bubble)
`header_collapse` boolean	Allow visitors to collapse the header area for more chat space
`typing` boolean	Show a typing indicator animation while the AI is generating a response
`streaming_active` boolean	Stream AI responses word-by-word instead of showing the complete message at once
`voice_active` boolean	Enable voice input — visitors can send messages using their microphone
`link_tracking_active` boolean	Track when visitors click links in AI responses. Tracked clicks appear as `tracked_link` events in Conversation Events
`white_label` boolean	Remove “Powered by Quickchat” branding from the widget

Pre-chat Form

Field	Description
`prechat_active` boolean	Enable the pre-chat form. When active, visitors must fill in the form before chatting
`prechat_header_text` string or null	Header text for the pre-chat form
`prechat_button_text` string or null	Label for the submit button on the pre-chat form
`prechat_message_text` string or null	Body text/instructions shown in the pre-chat form (HTML)

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Request Body — All fields are optional. Only include the fields you want to update.

AI Agent Avatar unification

The chat avatar (header logo) and the floating bubble icon (launcher) were merged into a single image, the AI Agent Avatar, stored in avatar_image. The bubble icon always mirrors it — there is no longer an independent launcher image. If you integrate with this endpoint directly, note the following behavior changes:

Uploading via bubble_icon_image is deprecated: it now sets the unified AI Agent Avatar, which also replaces the image shown in the chat header. Use avatar_image instead.
bubble_icon_image: null is a no-op. It used to clear the launcher icon; since the launcher mirrors the avatar, delete via avatar_image: null instead.
Agents that never customized their avatar show the default AI Agent Avatar (see default_avatar_image in the response) in both the header and the launcher.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Response 200 OK — Returns the updated widget configuration (same schema as Get Widget Configuration response).

Widget Configuration