הגדרות ווידג'ט

קריאה ועדכון של הגדרות ווידג'ט האתר דרך ה-API.

בדיקות דוגמה אופציונליות

בדיקת קטע קוד של ווידג’ט. בדקו קוד שהדבקתם מול מזהה התרחיש שסיפקתם. אין גישה לאתר שלכם.

בדפדפן תואם הבדיקות זמינות גם ככלי אתר. הקישורים פותחים את הטפסים הרגילים.

הווידג’ט הוא ממשק צ’אט שמטמיעים באתר. הוא מופיע כבועה צפה בפינת הדף שהמבקר יכול ללחוץ עליה לשיחה עם הסוכן. אפשר להתאים צבעים, גודל, מיקום, הודעות פתיחה והתנהגות.

ההגדרות משפיעות גם על ההטמעה, גרסה של אותו ממשק בגודל דף מלא או בתוך הדף, שאפשר לשלב ישירות בפריסה במקום בועה צפה. שניהם חולקים הגדרות מראה, הודעות והתנהגות.

באמצעות נקודות הקצה אפשר להתאים בתכנות את הופעת 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` מחרוזת	הודעת פתיחה ראשית בעת פתיחת הווידג’ט (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	כתובת תמונת סוכן AI, המוצגת גם בכותרת וגם כסמל הבועה. העלאה ב-PATCH כ-base64. `null` מציין שנמחקה ואין תמונה
`bubble_icon_image` מחרוזת או null	מיושן. תמיד משקף `avatar_image`; סמל הבועה ותמונת הצ’אט הם תמונה אחת (ראו איחוד תמונת הסוכן)
`default_avatar_image` מחרוזת	קריאה בלבד. כתובת תמונת ברירת המחדל ש-`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` בוליאני	הצגת מחוון הקלדה בזמן יצירת התשובה
`streaming_active` בוליאני	הזרמת תשובות מילה אחר מילה במקום הודעה מלאה בבת אחת
`voice_active` בוליאני	הפעלת קלט קולי מהמיקרופון
`attachments_active` בוליאני	מאפשר צירוף תמונה או מסמך. ברירת מחדל `true`; הגדירו `false` להסתרת הכפתור ולדחיית העלאות
`link_tracking_active` בוליאני	מעקב לחיצות על קישורים בתשובות. לחיצות מופיעות כאירועי `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. התגובה מחזירה את הכתובת השמורה. שליחת avatar_image: null מוחקת את התמונה, ושליחת use_default_avatar: true משחזרת את תמונת ברירת המחדל.

איחוד תמונת הסוכן

תמונת הצ’אט בכותרת וסמל הבועה הצפה אוחדו לתמונת סוכן AI אחת הנשמרת ב-avatar_image. הבועה תמיד משקפת אותה; אין עוד תמונת משגר עצמאית. בחיבור ישיר לנקודה זו, שימו לב לשינויים הבאים:

העלאה דרך bubble_icon_image מיושנת: היא מגדירה כעת את התמונה המאוחדת ומחליפה גם את התמונה בכותרת. השתמשו ב-avatar_image.
bubble_icon_image: null אינו עושה דבר. בעבר הוא ניקה את סמל המשגר; כעת יש למחוק באמצעות avatar_image: null.
סוכנים שלא שינו תמונה מציגים את ברירת המחדל (ראו 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: מחזירה הגדרות מעודכנות באותה סכימה של קבלת הגדרות ווידג’ט.

הגדרות ווידג'ט

בדיקות דוגמה אופציונליות