Widget Configuration

Read and update the website widget configuration via the API.

Ta treść nie jest jeszcze dostępna w Twoim języku.

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",
  "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",
  "avatar_image": "",
  "bubble_icon_image": ""
}

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…”)
`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	Widget size preset: `"small"`, `"medium"`, or `"large"`
`location` string	Widget position on the page: `"bottom-right"`, `"bottom-left"`, `"top-right"`, or `"top-left"`
`window_height` integer	Widget height in pixels (400-1000)
`window_width` integer	Widget width in pixels (250-1920)
`avatar_image` string	URL of the avatar image shown in the chat. Upload via PATCH as base64
`bubble_icon_image` string	URL of the floating bubble icon. Upload via PATCH as base64

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.

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