Widget Configuration

Optional example checks

• Check a Widget snippet. Check pasted code against the supplied Scenario ID. This does not fetch your website.

In a compatible browser, these checks are also available as site tools. The links open the standard forms.

Widget Configuration

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.

Get Widget Configuration

Scope: read_all

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

Shell

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

Python

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,
  "attachments_active": true,
  "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",
      "sidebar": {
        "background": "#f5f5f5",
        "text": null,
        "accent": "#e5e5e5",
        "accent_text": null
      }
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" },
    "transparency": { "style": "none", "opacity": 70 }
  }
}

Content & Messaging

Field	Description
welcome_message string	Primary welcome message displayed when widget opens (HTML). Dashboard: Channels > Your Website > Text Content > Welcome message
welcome_message2 string	Secondary welcome message shown below the primary greeting. Available through the API; there is no editor field for it in the Dashboard.
header string	Text displayed in the widget header bar. Dashboard: Channels > Your Website > Text Content > Header text
subtitle string	Subtitle text shown below the header. Available through the API; there is no editor field for it in the Dashboard.
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", "bottom-middle", 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	Theme customization. colors (header, accent, message bubble, AI text, link, input, border, and more, as hex or rgb()/rgba()) apply only when theme is "custom"; radius ("sm"/"base"/"lg"/"full" for bubbles, input, and buttons), font.size ("sm"/"base"/"lg"), and transparency apply in every theme mode. transparency.style is "none" (solid, the default) or "glass" (see-through with the page behind blurred); transparency.opacity (40–95, default 70) is the Glass tint in percent, and the widget never renders it thinner than the theme’s text needs over any website (50 in Light, 65 in Dark, derived from the colors in Custom). If no opacity keeps a Custom palette’s text readable, the widget renders solid, and the saved transparency.style stays "glass". The Chat Page always renders solid. On PATCH, send the whole object: missing keys reset to defaults, so an older object without transparency turns it back to "none". widget_theme_custom and each of its sections (colors, radius, font, transparency) must be an object; null takes the defaults of the whole theme or of that section, and any other value is rejected with 422. colors.link defaults to null, meaning links inherit the surrounding text color. colors.sidebar (background, text, accent, accent_text) themes the standalone Chat Page sidebar only (ignored by the bubble and embed views); its text and accent_text default to null, meaning a readable color is auto-derived from the matching background

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
attachments_active boolean	Allow visitors to attach an image or document to a message. Defaults to true; set to false to hide the attachment button and reject uploads
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)

Update Widget Configuration

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.

Note

For avatar_image, send base64-encoded image data (max 5 MB). The response returns the stored image URL. Sending avatar_image: null deletes the avatar (the widget then shows no avatar), and sending use_default_avatar: true restores the default AI Agent Avatar.

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

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
}'

Python

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

---