Widget 設定

透過 API 讀取及更新網站 Widget 設定。

選用範例檢查

檢查 Widget 程式碼片段。依提供的 Scenario ID 檢查貼上的程式碼，不會擷取您的網站。

相容瀏覽器也能將這些檢查作為網站工具使用。連結會開啟一般表單。

Widget 是嵌入網站的聊天介面，以頁面角落的浮動泡泡呈現。訪客按一下即可開啟與 AI Agent 的對話。Widget 可完整自訂，您能控制顏色、大小、位置、歡迎訊息與行為。

這些設定也會影響嵌入區塊，它是同一聊天介面的全頁或行內版本，可直接放進網頁版面，而非浮動泡泡。Widget 與嵌入區塊共用外觀、訊息與行為設定。

透過這些端點，您可以程式化自訂 Quickchat AI 在網站的呈現方式，例如配合品牌顏色、設定聊天前表單以收集訪客資料、設定輸入中指示、啟用語音輸入等。設定步驟請見網站通路指南。

權限範圍：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()

回應 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 }
  }
}

內容與訊息

欄位	說明
`welcome_message` 字串	Widget 開啟時顯示的主要歡迎訊息（HTML）。控制台：通路 > 您的網站 > 文字內容 > 歡迎訊息
`welcome_message2` 字串	顯示於主要歡迎訊息下方的次要訊息。可透過 API 使用，控制台沒有對應編輯欄位。
`header` 字串	Widget 頂部列的文字。控制台：通路 > 您的網站 > 文字內容 > 頂部文字
`subtitle` 字串	標題下方的副標題文字。可透過 API 使用，控制台沒有對應編輯欄位。
`input_placeholder` 字串	訊息輸入欄位的提示文字，例如「輸入您的訊息…」
`conversation_starters` 字串陣列或 null	Widget 開啟時以可點選按鈕顯示的建議開場問題。最多 3 項，每項約 100 個字元
`background_disclaimer_text` 字串或 null	聊天視窗底部顯示的免責聲明文字

外觀

欄位	說明
`primary_color` 字串	Widget 強調色，以 CSS rgb 值表示，例如 `"rgb(0, 122, 255)"`。用於按鈕、連結與使用者訊息泡泡
`header_color` 字串	頂部背景顏色，以 CSS rgb 值表示
`header_text_color` 布林值	頂部文字亮度。`true` = 白色/淺色文字（適用深色頂部）；`false` = 深色文字（適用淺色頂部）。注意：雖然名稱如此，此欄位是布林值，不是顏色字串
`size` 字串	啟動按鈕大小預設：`"small"`、`"medium"` 或 `"large"`，在控制台顯示為小、僅輸入欄位、經典
`location` 字串	Widget 在頁面的所在位置：`"top-left"`、`"top-right"`、`"bottom-left"`、`"bottom-middle"` 或 `"bottom-right"`
`launcher_label` 字串或 null	小型啟動按鈕（`size: "small"`）上的文字，最多 25 個字元。`null` 使用預設值（`"Ask AI"`）；`""` 顯示僅有圖示的啟動按鈕
`launcher_draggable` 布林值	允許訪客將啟動按鈕拖曳到頁面的其他位置
`window_height` 整數	Widget 高度，單位為像素（400-1200）
`window_width` 整數	Widget 寬度，單位為像素（300-700）
`avatar_image` 字串或 null	AI Agent 頭像的 URL，同時顯示於聊天頂部與浮動泡泡圖示。透過 PATCH 以 base64 上傳。`null` 表示頭像已刪除，Widget 不顯示頭像
`bubble_icon_image` 字串或 null	已棄用。一律與 `avatar_image` 相同，泡泡圖示與聊天頭像現在是同一張圖片，請參閱 AI Agent 頭像統一
`default_avatar_image` 字串	唯讀。`use_default_avatar` 所還原的預設 AI Agent 頭像 URL
`theme` 字串	色彩主題模式：`"light"` 或 `"dark"`（固定預設），或 `"custom"`（套用 `widget_theme_custom` 色盤）
`widget_theme_custom` 物件	主題自訂設定。`colors`（頂部、強調色、訊息泡泡、AI 文字、`link`、輸入、邊框等，使用十六進位或 `rgb()`/`rgba()`）僅在 `theme` 為 `"custom"` 時套用；`radius`（泡泡、輸入框與按鈕的 `"sm"`/`"base"`/`"lg"`/`"full"`）、`font.size`（`"sm"`/`"base"`/`"lg"`）與 `transparency` 則適用於所有主題模式。`transparency.style` 為 `"none"`（純色，預設）或 `"glass"`（透明並模糊後方頁面）；`transparency.opacity`（40–95，預設 70）是玻璃色調的百分比。Widget 不會讓背景比文字在任意網站上保持可讀所需的最低濃度更淡，淺色為 50、深色為 65，自訂則依顏色推算。若任何不透明度都無法讓自訂色盤的文字易讀，Widget 會以純色呈現，但已儲存的 `transparency.style` 仍為 `"glass"`。聊天頁面一律使用純色。PATCH 時請傳送整個物件；缺少的鍵會重設為預設值，因此不含 `transparency` 的舊物件會將其改回 `"none"`。`widget_theme_custom` 及其各區段（`colors`、`radius`、`font`、`transparency`）都必須是物件；`null` 會採用整個主題或該區段的預設值，其他值則以 422 拒絕。`colors.link` 預設為 `null`，表示連結繼承周圍文字顏色。`colors.sidebar`（`background`、`text`、`accent`、`accent_text`）只設定獨立聊天頁面的側欄，泡泡與嵌入檢視會忽略；其中 `text` 與 `accent_text` 預設為 `null`，會依對應背景自動選取可讀顏色

行為

欄位	說明
`popup_active` 布林值	在 Widget 泡泡附近顯示彈出提示，鼓勵訪客開始對話
`window_auto_open` 布林值	頁面載入時自動開啟 Widget，而非僅顯示泡泡
`header_collapse` 布林值	允許訪客收合頂部區域以增加聊天空間
`typing` 布林值	AI 產生回覆時顯示輸入中動畫
`streaming_active` 布林值	逐字串流 AI 回覆，而非一次顯示完整訊息
`voice_active` 布林值	啟用語音輸入，讓訪客可透過麥克風傳送訊息
`attachments_active` 布林值	允許訪客在訊息附加圖片或文件。預設為 `true`；設為 `false` 會隱藏附件按鈕並拒絕上傳
`link_tracking_active` 布林值	追蹤訪客點選 AI 回覆連結的行為。追蹤的點選會在對話事件中顯示為 `tracked_link` 事件
`white_label` 布林值	移除 Widget 的「Powered by Quickchat」品牌標示

聊天前表單

欄位	說明
`prechat_active` 布林值	啟用聊天前表單。啟用後，訪客必須先填表才能聊天
`prechat_header_text` 字串或 null	聊天前表單的標題文字
`prechat_button_text` 字串或 null	聊天前表單送出按鈕的標籤
`prechat_message_text` 字串或 null	聊天前表單顯示的本文/指示文字（HTML）

權限範圍：write_all

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

請求本文：所有欄位皆為選填。僅包含要更新的欄位。

對 avatar_image，請傳送 base64 編碼的圖片資料（最大 5 MB）。回應傳回已儲存的圖片 URL。傳送 avatar_image: null 會刪除頭像，Widget 將不顯示頭像；傳送 use_default_avatar: true 則還原預設 AI Agent 頭像。

AI Agent 頭像統一

聊天頭像（頂部標誌）與浮動泡泡圖示（啟動按鈕）已合併為同一張 AI Agent 頭像，儲存於 avatar_image。泡泡圖示一律與其相同，不再有獨立的啟動按鈕圖片。若直接整合此端點，請注意下列行為變更：

透過 bubble_icon_image 上傳已棄用：現在會設定統一的 AI Agent 頭像，也會替換聊天頂部圖片。請改用 avatar_image。
bubble_icon_image: null 不會執行任何操作。過去它會清除啟動圖示；由於啟動按鈕現在與頭像相同，請改用 avatar_image: null 刪除。
從未自訂頭像的 Agent，會在頂部與啟動按鈕同時顯示預設 AI Agent 頭像，請見回應中的 default_avatar_image。

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

回應 200 OK：傳回更新後的 Widget 設定，結構與取得 Widget 設定回應相同。

Widget 設定

選用範例檢查

Widget 設定

取得 Widget 設定

內容與訊息

外觀

行為

聊天前表單

更新 Widget 設定

AI Agent 頭像統一

開始使用

AI Agent

Actions

對話

Channels

您的網站

Helpdesk 與 CRM

通訊應用程式

帳戶與帳務

開始使用

設定

Knowledge Base

對話