# Widget Configuration

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

## 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](/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",
  "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` <br/> string | Primary welcome message displayed when widget opens (HTML). Dashboard: **Website > Greeting** |
| `welcome_message2` <br/> string | Secondary welcome message shown below the primary greeting |
| `header` <br/> string | Text displayed in the widget header bar. Dashboard: **Website > Header** |
| `subtitle` <br/> string | Subtitle text shown below the header. Dashboard: **Website > Subtitle** |
| `input_placeholder` <br/> string | Placeholder text in the message input field (e.g., "Type your message...") |
| `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 | Widget size preset: `"small"`, `"medium"`, or `"large"` |
| `location` <br/> string | Widget position on the page: `"bottom-right"`, `"bottom-left"`, `"top-right"`, or `"top-left"` |
| `window_height` <br/> integer | Widget height in pixels (400-1000) |
| `window_width` <br/> integer | Widget width in pixels (250-1920) |
| `avatar_image` <br/> string | URL of the avatar image shown in the chat. Upload via PATCH as base64 |
| `bubble_icon_image` <br/> string | URL of the floating bubble icon. Upload via PATCH as base64 |

#### 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 |
| `link_tracking_active` <br/> boolean | Track when visitors click links in AI responses. Tracked clicks appear as `tracked_link` events in [Conversation Events](#get-conversation-events) |
| `white_label` <br/> boolean | Remove "Powered by Quickchat" branding from the widget |

#### Pre-chat Form

| Field | Description |
|-------|-------------|
| `prechat_active` <br/> boolean | Enable the pre-chat form. When active, visitors must fill in the form before chatting |
| `prechat_header_text` <br/> string or null | Header text for the pre-chat form |
| `prechat_button_text` <br/> string or null | Label for the submit button on the pre-chat form |
| `prechat_message_text` <br/> 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 image fields (`avatar_image`, `bubble_icon_image`), send base64-encoded image data (max 5 MB). The response returns the stored image URL.
:::

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

---