Cấu hình Widget

Đọc và cập nhật cấu hình widget website qua API.

Kiểm tra ví dụ tùy chọn

Kiểm tra đoạn mã Widget. Kiểm tra mã dán vào theo Scenario ID được cung cấp. Không truy cập website của bạn.

Trong trình duyệt tương thích, các phép kiểm tra này cũng có dưới dạng công cụ website. Liên kết mở biểu mẫu tiêu chuẩn.

Widget là giao diện chat nhúng vào website, xuất hiện như bong bóng nổi ở góc trang để khách nhấp mở cuộc trò chuyện với AI Agent. Bạn có thể tùy chỉnh hoàn toàn màu sắc, kích thước, vị trí, lời chào và hành vi.

Các cài đặt cũng ảnh hưởng bản nhúng, tức phiên bản toàn trang hoặc nằm trong bố cục của cùng giao diện chat, có thể đặt trực tiếp vào trang web thay vì bong bóng nổi. Widget và bản nhúng dùng chung cấu hình giao diện, tin nhắn và hành vi.

Với các endpoint này, bạn có thể tùy chỉnh bằng lập trình cách Quickchat AI xuất hiện trên website: dùng màu thương hiệu, thiết lập biểu mẫu trước chat để thu thập thông tin khách, cấu hình chỉ báo đang nhập, bật giọng nói và nhiều hơn nữa. Xem Hướng dẫn kênh website để biết cách thiết lập.

Phạm vi: 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()

Phản hồi 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 }
  }
}

Nội dung và tin nhắn

Trường	Mô tả
`welcome_message` chuỗi	Lời chào chính khi widget mở (HTML). Bảng điều khiển: Kênh > Trang web của bạn > Nội dung văn bản > Lời chào
`welcome_message2` chuỗi	Lời chào phụ bên dưới lời chào chính. Có qua API; không có trường chỉnh sửa trong bảng điều khiển.
`header` chuỗi	Văn bản ở thanh đầu widget. Bảng điều khiển: Kênh > Trang web của bạn > Nội dung văn bản > Văn bản phần đầu
`subtitle` chuỗi	Văn bản phụ đề bên dưới phần đầu. Có qua API; không có trường chỉnh sửa trong bảng điều khiển.
`input_placeholder` chuỗi	Văn bản gợi ý trong ô nhập tin nhắn (ví dụ “Nhập tin nhắn…”)
`conversation_starters` mảng chuỗi hoặc null	Câu mở đầu gợi ý dưới dạng nút khi widget mở. Tối đa 3 mục, mỗi mục khoảng 100 ký tự
`background_disclaimer_text` chuỗi hoặc null	Văn bản tuyên bố miễn trừ ở cuối cửa sổ chat

Giao diện

Trường	Mô tả
`primary_color` chuỗi	Màu nhấn widget dạng giá trị CSS rgb (ví dụ `"rgb(0, 122, 255)"`). Dùng cho nút, liên kết và bong bóng tin nhắn người dùng
`header_color` chuỗi	Màu nền phần đầu dạng CSS rgb
`header_text_color` boolean	Độ sáng chữ phần đầu. `true` = chữ trắng/sáng (cho nền tối), `false` = chữ tối (cho nền sáng). Lưu ý: dù tên như vậy, đây là boolean, không phải chuỗi màu
`size` chuỗi	Cỡ nút mở: `"small"`, `"medium"` hoặc `"large"` (trong bảng điều khiển là Nhỏ, Chỉ ô nhập và Cổ điển)
`location` chuỗi	Vị trí widget trên trang: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` hoặc `"bottom-right"`
`launcher_label` chuỗi hoặc null	Chữ trên nút mở nhỏ (`size: "small"`), tối đa 25 ký tự. `null` dùng mặc định (`"Ask AI"`); `""` chỉ hiển thị biểu tượng
`launcher_draggable` boolean	Cho phép khách kéo nút mở sang vị trí khác trên trang
`window_height` số nguyên	Chiều cao widget bằng pixel (400-1200)
`window_width` số nguyên	Chiều rộng widget bằng pixel (300-700)
`avatar_image` chuỗi hoặc null	URL Ảnh đại diện AI Agent, hiển thị ở phần đầu chat và biểu tượng bong bóng nổi. Tải qua PATCH bằng base64. `null` nghĩa là đã xóa ảnh đại diện và widget không hiển thị ảnh
`bubble_icon_image` chuỗi hoặc null	Không còn dùng. Luôn phản chiếu `avatar_image`; biểu tượng bong bóng và ảnh đại diện chat hiện là cùng một ảnh (xem Hợp nhất Ảnh đại diện AI Agent)
`default_avatar_image` chuỗi	Chỉ đọc. URL Ảnh đại diện AI Agent mặc định được khôi phục bởi `use_default_avatar`
`theme` chuỗi	Chế độ màu: `"light"` hoặc `"dark"` (cấu hình cố định), hoặc `"custom"` (áp dụng bảng màu `widget_theme_custom`)
`widget_theme_custom` đối tượng	Tùy chỉnh chủ đề. `colors` (phần đầu, màu nhấn, bong bóng tin nhắn, chữ AI, `link`, ô nhập, viền và các màu khác, dạng hex hoặc `rgb()`/`rgba()`) chỉ áp dụng khi `theme` là `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` cho bong bóng, ô nhập, nút), `font.size` (`"sm"`/`"base"`/`"lg"`) và `transparency` áp dụng ở mọi chế độ. `transparency.style` là `"none"` (đặc, mặc định) hoặc `"glass"` (xuyên thấu với trang phía sau làm mờ); `transparency.opacity` (40–95, mặc định 70) là phần trăm sắc độ Kính. Widget không bao giờ hiển thị mỏng hơn mức chữ cần trên bất kỳ website nào (50 ở Sáng, 65 ở Tối, suy ra từ màu ở Tùy chỉnh). Nếu không độ mờ nào giữ chữ bảng màu Tùy chỉnh dễ đọc, widget hiển thị đặc nhưng `transparency.style` đã lưu vẫn là `"glass"`. Trang chat luôn hiển thị đặc. Khi PATCH, gửi toàn bộ đối tượng: khóa thiếu đặt lại mặc định, nên đối tượng cũ không có `transparency` sẽ đưa nó về `"none"`. `widget_theme_custom` và từng phần (`colors`, `radius`, `font`, `transparency`) phải là đối tượng; `null` dùng mặc định của toàn chủ đề hoặc phần đó, giá trị khác bị từ chối với 422. `colors.link` mặc định `null`, nghĩa là liên kết kế thừa màu chữ xung quanh. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) chỉ định kiểu thanh bên Trang chat độc lập (bong bóng và bản nhúng bỏ qua); `text` và `accent_text` mặc định `null`, nghĩa là tự suy ra màu dễ đọc từ nền tương ứng

Hành vi

Trường	Mô tả
`popup_active` boolean	Hiện lời nhắc gần bong bóng widget để khuyến khích khách bắt đầu chat
`window_auto_open` boolean	Tự mở widget khi trang tải (thay vì chỉ hiện bong bóng)
`header_collapse` boolean	Cho phép khách thu gọn phần đầu để có thêm không gian chat
`typing` boolean	Hiện hiệu ứng đang nhập khi AI tạo câu trả lời
`streaming_active` boolean	Truyền phản hồi AI từng từ thay vì hiển thị toàn bộ cùng lúc
`voice_active` boolean	Bật nhập giọng nói; khách có thể gửi tin nhắn bằng micrô
`attachments_active` boolean	Cho phép khách đính kèm ảnh hoặc tài liệu vào tin nhắn. Mặc định `true`; đặt `false` để ẩn nút đính kèm và từ chối tải lên
`link_tracking_active` boolean	Theo dõi khi khách nhấp liên kết trong câu trả lời AI. Lượt nhấp xuất hiện thành sự kiện `tracked_link` trong Sự kiện cuộc trò chuyện
`white_label` boolean	Xóa thương hiệu “Powered by Quickchat” khỏi widget

Biểu mẫu trước chat

Trường	Mô tả
`prechat_active` boolean	Bật biểu mẫu trước chat. Khi bật, khách phải điền trước khi trò chuyện
`prechat_header_text` chuỗi hoặc null	Văn bản phần đầu biểu mẫu trước chat
`prechat_button_text` chuỗi hoặc null	Nhãn nút gửi trên biểu mẫu trước chat
`prechat_message_text` chuỗi hoặc null	Nội dung/hướng dẫn trên biểu mẫu trước chat (HTML)

Phạm vi: write_all

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

Nội dung yêu cầu: mọi trường đều tùy chọn. Chỉ thêm trường muốn cập nhật.

Với avatar_image, gửi dữ liệu ảnh mã hóa base64 (tối đa 5 MB). Phản hồi trả URL ảnh đã lưu. Gửi avatar_image: null để xóa ảnh (widget không còn hiển thị ảnh đại diện), và gửi use_default_avatar: true để khôi phục Ảnh đại diện AI Agent mặc định.

Hợp nhất Ảnh đại diện AI Agent

Ảnh đại diện chat (logo phần đầu) và biểu tượng bong bóng nổi (nút mở) đã được hợp nhất thành Ảnh đại diện AI Agent, lưu trong avatar_image. Biểu tượng bong bóng luôn dùng cùng ảnh; không còn ảnh nút mở riêng. Nếu tích hợp trực tiếp endpoint này, lưu ý các thay đổi hành vi sau:

Tải lên qua bubble_icon_image không còn được khuyến nghị: nay đặt Ảnh đại diện AI Agent hợp nhất, đồng thời thay ảnh phần đầu chat. Dùng avatar_image thay thế.
bubble_icon_image: null không làm gì. Trước đây xóa biểu tượng nút mở; vì nay dùng cùng ảnh đại diện, hãy xóa bằng avatar_image: null.
Agent chưa từng tùy chỉnh ảnh đại diện hiển thị Ảnh đại diện AI Agent mặc định (xem default_avatar_image trong phản hồi) ở cả phần đầu và nút mở.

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

Phản hồi 200 OK: trả về cấu hình widget đã cập nhật (cùng cấu trúc với phản hồi Lấy cấu hình Widget).

Cấu hình Widget

Kiểm tra ví dụ tùy chọn