การตั้งค่าวิดเจ็ต

ตัวอย่างการตรวจสอบเพิ่มเติม

• ตรวจสอบโค้ด Widget ตรวจโค้ดที่วางเทียบกับ Scenario ID ที่ระบุ การตรวจสอบนี้ไม่ดึงเว็บไซต์ของคุณ

ในเบราว์เซอร์ที่รองรับ การตรวจสอบเหล่านี้มีให้เป็นเครื่องมือของเว็บไซต์ด้วย ลิงก์จะเปิดแบบฟอร์มมาตรฐาน

การตั้งค่าวิดเจ็ต

วิดเจ็ต คือส่วนติดต่อแชตที่ฝังบนเว็บไซต์ โดยแสดงเป็นปุ่มลอยที่มุมหน้าให้ผู้เยี่ยมชมคลิกเปิดบทสนทนากับ AI Agent วิดเจ็ตปรับแต่งได้ครบถ้วน ทั้งสี ขนาด ตำแหน่ง ข้อความทักทาย และพฤติกรรม

การตั้งค่าเหล่านี้มีผลกับ แชตแบบฝัง ด้วย ซึ่งเป็นส่วนติดต่อแชตเดียวกันแบบเต็มหน้าหรือในหน้า ที่วางตรงในเค้าโครงเว็บไซต์ได้แทนปุ่มลอย ทั้งวิดเจ็ตและแชตแบบฝังใช้การตั้งค่ารูปลักษณ์ ข้อความ และพฤติกรรมร่วมกัน

เอนด์พอยต์เหล่านี้ช่วยปรับวิธีแสดง Quickchat AI บนเว็บไซต์ด้วยโปรแกรม เช่น ให้สีตรงกับแบรนด์ ตั้งแบบฟอร์มก่อนแชตเพื่อเก็บข้อมูลผู้เยี่ยมชม ตั้งค่าตัวแสดงการพิมพ์ เปิดป้อนข้อมูลด้วยเสียง และอื่น ๆ ดูขั้นตอนติดตั้งใน คู่มือช่องทางเว็บไซต์

ดึงการตั้งค่าวิดเจ็ต

ขอบเขตสิทธิ์: read_all

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

Shell

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

Python

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 สตริง	ข้อความต้อนรับหลักเมื่อเปิดวิดเจ็ต (HTML) ในแดชบอร์ด: ช่องทาง > เว็บไซต์ของคุณ > เนื้อหาข้อความ > ข้อความต้อนรับ
welcome_message2 สตริง	ข้อความต้อนรับรองที่แสดงใต้คำทักทายหลัก ใช้ได้ผ่าน API แต่ไม่มีฟิลด์แก้ไขในแดชบอร์ด
header สตริง	ข้อความที่แสดงในแถบส่วนหัววิดเจ็ต ในแดชบอร์ด: ช่องทาง > เว็บไซต์ของคุณ > เนื้อหาข้อความ > ข้อความส่วนหัว
subtitle สตริง	ข้อความรองใต้ส่วนหัว ใช้ได้ผ่าน API แต่ไม่มีฟิลด์แก้ไขในแดชบอร์ด
input_placeholder สตริง	ข้อความตัวอย่างในช่องป้อนข้อความ (เช่น “พิมพ์ข้อความของคุณ…”)
conversation_starters อาร์เรย์ของสตริง หรือ null	ข้อความแนะนำเริ่มสนทนาที่แสดงเป็นปุ่มคลิกได้เมื่อเปิดวิดเจ็ต สูงสุด 3 รายการ รายการละประมาณ 100 อักขระ
background_disclaimer_text สตริง หรือ null	ข้อความข้อจำกัดความรับผิดชอบที่แสดงด้านล่างหน้าต่างแชต

รูปลักษณ์

ฟิลด์	คำอธิบาย
primary_color สตริง	สีเน้นของวิดเจ็ตเป็นค่า CSS rgb (เช่น "rgb(0, 122, 255)") ใช้กับปุ่ม ลิงก์ และกล่องข้อความผู้ใช้
header_color สตริง	สีพื้นหลังส่วนหัวเป็นค่า CSS rgb
header_text_color บูลีน	ความสว่างข้อความส่วนหัว true = ข้อความสีขาว/สว่าง (สำหรับส่วนหัวสีเข้ม), false = ข้อความสีเข้ม (สำหรับส่วนหัวสีอ่อน) หมายเหตุ: แม้ชื่อจะกล่าวถึงสี แต่ค่านี้เป็นบูลีน ไม่ใช่สตริงสี
size สตริง	ขนาดปุ่มเปิดแชต: "small", "medium" หรือ "large" (แสดงในแดชบอร์ดเป็น เล็ก, เฉพาะช่องป้อนข้อมูล และ คลาสสิก)
location สตริง	ตำแหน่งวิดเจ็ตบนหน้า: "top-left", "top-right", "bottom-left", "bottom-middle" หรือ "bottom-right"
launcher_label สตริง หรือ null	ข้อความบนปุ่มเปิดแชตขนาด เล็ก (size: "small") สูงสุด 25 อักขระ null ใช้ค่าเริ่มต้น ("Ask AI"), "" แสดงเฉพาะไอคอน
launcher_draggable บูลีน	อนุญาตให้ผู้เยี่ยมชมลากปุ่มเปิดแชตไปตำแหน่งอื่นบนหน้า
window_height จำนวนเต็ม	ความสูงวิดเจ็ตเป็นพิกเซล (400-1200)
window_width จำนวนเต็ม	ความกว้างวิดเจ็ตเป็นพิกเซล (300-700)
avatar_image สตริง หรือ null	URL ของ รูปประจำตัวเอเจนต์ AI ซึ่งแสดงทั้งในส่วนหัวแชตและเป็นไอคอนปุ่มลอย อัปโหลดผ่าน PATCH เป็น base64 ค่า null หมายถึงลบรูปแล้วและวิดเจ็ตไม่แสดงรูปประจำตัว
bubble_icon_image สตริง หรือ null	เลิกใช้แล้ว มีค่าเดียวกับ avatar_image เสมอ ปัจจุบันไอคอนปุ่มลอยและรูปในแชตเป็นภาพเดียวกัน (ดู การรวมรูปประจำตัวเอเจนต์ AI)
default_avatar_image สตริง	อ่านอย่างเดียว URL รูปประจำตัวเอเจนต์ AI เริ่มต้นที่ use_default_avatar ใช้คืนค่า
theme สตริง	โหมดสี: "light" หรือ "dark" (รูปแบบคงที่) หรือ "custom" (ใช้ชุดสี widget_theme_custom)
widget_theme_custom ออบเจ็กต์	การปรับแต่งธีม colors (ส่วนหัว สีเน้น กล่องข้อความ ข้อความ AI, link, ช่องป้อนข้อมูล เส้นขอบ และอื่น ๆ เป็น hex หรือ rgb()/rgba()) มีผลเมื่อ theme เป็น "custom" เท่านั้น ส่วน radius ("sm"/"base"/"lg"/"full" สำหรับกล่องข้อความ ช่องป้อนข้อมูล และปุ่ม), font.size ("sm"/"base"/"lg") และ transparency มีผลทุกโหมดธีม transparency.style เป็น "none" (ทึบ ค่าเริ่มต้น) หรือ "glass" (โปร่งเห็นหน้าเว็บด้านหลังแบบเบลอ) ค่า transparency.opacity (40–95 ค่าเริ่มต้น 70) คือเปอร์เซ็นต์ความทึบของกระจก และวิดเจ็ตจะไม่แสดงจางจนอ่านข้อความไม่ได้เมื่ออยู่บนเว็บไซต์ใด ๆ (50 ในโหมดสว่าง, 65 ในโหมดมืด และคำนวณจากสีในโหมดกำหนดเอง) หากไม่มีค่าความทึบใดทำให้ข้อความในชุดสีกำหนดเองอ่านได้ วิดเจ็ตจะแสดงแบบทึบ แต่ค่า 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 บูลีน	แสดงข้อความป๊อปอัปใกล้ปุ่มลอยวิดเจ็ตเพื่อเชิญให้ผู้เยี่ยมชมเริ่มสนทนา
window_auto_open บูลีน	เปิดวิดเจ็ตโดยอัตโนมัติเมื่อโหลดหน้า (แทนการแสดงเฉพาะปุ่มลอย)
header_collapse บูลีน	อนุญาตให้ผู้เยี่ยมชมยุบส่วนหัวเพื่อเพิ่มพื้นที่แชต
typing บูลีน	แสดงภาพเคลื่อนไหวการพิมพ์ขณะ AI สร้างคำตอบ
streaming_active บูลีน	แสดงคำตอบ AI ทีละคำแบบสตรีมแทนการแสดงข้อความเต็มในครั้งเดียว
voice_active บูลีน	เปิดการป้อนข้อมูลด้วยเสียง ผู้เยี่ยมชมส่งข้อความผ่านไมโครโฟนได้
attachments_active บูลีน	อนุญาตให้ผู้เยี่ยมชมแนบรูปภาพหรือเอกสารกับข้อความ ค่าเริ่มต้นคือ true ตั้งเป็น false เพื่อซ่อนปุ่มแนบไฟล์และปฏิเสธการอัปโหลด
link_tracking_active บูลีน	ติดตามเมื่อผู้เยี่ยมชมคลิกลิงก์ในคำตอบ AI การคลิกแสดงเป็นเหตุการณ์ tracked_link ใน เหตุการณ์ของบทสนทนา
white_label บูลีน	ลบแบรนด์ “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 จะลบรูปประจำตัว (วิดเจ็ตจะไม่แสดงรูป) และการส่ง use_default_avatar: true จะคืนรูปประจำตัวเอเจนต์ AI เริ่มต้น

การรวมรูปประจำตัวเอเจนต์ AI

รูปในแชต (โลโก้ส่วนหัว) และไอคอนปุ่มลอย (ปุ่มเปิดแชต) รวมเป็นภาพเดียวคือ รูปประจำตัวเอเจนต์ AI จัดเก็บใน avatar_image ไอคอนปุ่มลอยใช้ภาพเดียวกันเสมอ ไม่มีภาพปุ่มเปิดแชตแยกอีกต่อไป หากเชื่อมต่อเอนด์พอยต์นี้โดยตรง โปรดคำนึงถึงพฤติกรรมที่เปลี่ยนดังนี้:

• การอัปโหลดผ่าน bubble_icon_image เลิกใช้แล้ว: ตอนนี้จะกำหนดรูปประจำตัวเอเจนต์ AI แบบรวม ซึ่งแทนภาพส่วนหัวแชตด้วย ใช้ avatar_image แทน
• bubble_icon_image: null ไม่ทำอะไร เดิมใช้ล้างไอคอนปุ่มเปิดแชต แต่ตอนนี้ปุ่มใช้ภาพเดียวกับรูปประจำตัว ให้ลบด้วย avatar_image: null แทน
• Agent ที่ไม่เคยเปลี่ยนรูปจะแสดงรูปประจำตัวเอเจนต์ AI เริ่มต้น (ดู default_avatar_image ในการตอบกลับ) ทั้งในส่วนหัวและปุ่มเปิดแชต

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

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 ส่งกลับการตั้งค่าวิดเจ็ตที่อัปเดตแล้ว (โครงสร้างเดียวกับการตอบกลับของ ดึงการตั้งค่าวิดเจ็ต)

---