# Widget Configuration

> Read and update the website widget configuration via the API.

## Optional example checks

- [Check a Widget snippet][public-lab-widget-snippet-webmcp]. 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.

Use these endpoints to configure your website chat's colors, size, messages and behavior, including the Pre-chat Screen. For installation instructions, see the [Website channel guide](/docs/channels/website).

### Get Widget Configuration

**Scope: read_all**

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

**Shell**

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

**Python**

```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`

```json
{
  "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` <br/> string | Primary welcome message displayed when widget opens (HTML). Dashboard: **Channels > Your Website > Text Content > Welcome message** |
| `welcome_message2` <br/> string | Secondary welcome message shown below the primary greeting. Available through the API; there is no editor field for it in the Dashboard. |
| `header` <br/> string | Text displayed in the widget header bar. Dashboard: **Channels > Your Website > Text Content > Header text** |
| `subtitle` <br/> string | Subtitle text shown below the header. Available through the API; there is no editor field for it in the Dashboard. |
| `input_placeholder` <br/> string | Placeholder text in the message input field (e.g., "Type your message...") |
| `conversation_starters` <br/> 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` <br/> string or null | Disclaimer text shown at the bottom of the chat window |

#### Appearance

| Field | Description |
|-------|-------------|
| `primary_color` <br/> string | Widget accent color as CSS rgb value (e.g., `"rgb(0, 122, 255)"`). Used for buttons, links, and user message bubbles |
| `header_color` <br/> string | Header background color as CSS rgb value |
| `header_text_color` <br/> 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` <br/> string | Launcher size preset: `"small"`, `"medium"`, or `"large"` (shown in the dashboard as Small, Input Only, and Classic) |
| `location` <br/> string | Widget position on the page: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"`, or `"bottom-right"` |
| `launcher_label` <br/> 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` <br/> boolean | Allow visitors to drag the launcher to a different position on the page |
| `window_height` <br/> integer | Widget height in pixels (400-1200) |
| `window_width` <br/> integer | Widget width in pixels (300-700) |
| `avatar_image` <br/> 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` <br/> string or null | **Deprecated.** Always mirrors `avatar_image` — the bubble icon and the chat avatar are now one image (see [AI Agent Avatar unification](#ai-agent-avatar-unification)) |
| `default_avatar_image` <br/> string | Read-only. URL of the default AI Agent Avatar that `use_default_avatar` restores |
| `theme` <br/> string | Color theme mode: `"light"` or `"dark"` (fixed presets) or `"custom"` (applies the `widget_theme_custom` palette) |
| `widget_theme_custom` <br/> 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` <br/> boolean | Show a popup prompt near the widget bubble to encourage visitors to start a conversation |
| `window_auto_open` <br/> boolean | Automatically open the widget when the page loads (instead of showing just the bubble) |
| `header_collapse` <br/> boolean | Allow visitors to collapse the header area for more chat space |
| `typing` <br/> boolean | Show a typing indicator animation while the AI is generating a response |
| `streaming_active` <br/> boolean | Stream AI responses word-by-word instead of showing the complete message at once |
| `voice_active` <br/> boolean | Enable voice input — visitors can send messages using their microphone |
| `attachments_active` <br/> 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` <br/> boolean | Track when visitors click links in AI responses. Tracked clicks appear as `tracked_link` events in [Conversation Events](/docs/api-reference/conversations#get-conversation-events) |
| `white_label` <br/> boolean | Remove "Powered by Quickchat" branding from the widget |

<div id="pre-chat-form"></div>

#### Pre-chat Screen

| Field | Description |
|-------|-------------|
| `prechat_active` <br/> boolean | Show the Pre-chat Screen before the conversation; visitors use its start button to continue |
| `prechat_header_text` <br/> string or null | Heading on the Pre-chat Screen |
| `prechat_button_text` <br/> string or null | Label for the button that starts the conversation |
| `prechat_message_text` <br/> string or null | Message shown on the Pre-chat Screen (HTML) |

The standard website Widget shows a heading, message and start button on this screen. It has no email or phone inputs and cannot require these details before the chat starts. [Smart Data Gathering](/docs/ai-agent/actions/smart-data-gathering) can ask for them during the conversation. Requiring contact details before allowing chat needs a separate website form or custom integration.

### 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**

```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**

```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](#get-widget-configuration) response).

---

[public-lab-widget-snippet-webmcp]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/widget-snippet/lab/webmcp/?placement=docs-widget-api-widget-snippet-webmcp-v1
