إعداد Widget

فحوص أمثلة اختيارية

• تحقق من مقتطف Widget. افحص الكود الملصق مقابل Scenario ID المقدم. لا يجلب ذلك موقعك.

في المتصفح المتوافق، تتوفر هذه الفحوص أيضًا كأدوات للموقع. تفتح الروابط النماذج المعتادة.

إعداد Widget

Widget واجهة دردشة تضمّنها في موقعك، وتظهر كفقاعة عائمة في زاوية الصفحة يضغطها الزوار لبدء محادثة مع وكيل AI. يمكن تخصيص Widget بالكامل: تتحكم في ألوانه وحجمه وموقعه ورسائل الترحيب وسلوكه.

تؤثر هذه الإعدادات أيضًا على التضمين، وهو نسخة بملء الصفحة أو داخلها من واجهة الدردشة نفسها، يمكنك وضعها مباشرة في تخطيط الصفحة بدلًا من الفقاعة العائمة. يشترك Widget والتضمين في إعداد المظهر والرسائل والسلوك نفسه.

باستخدام هذه النقاط، يمكنك تخصيص ظهور Quickchat AI في موقعك برمجيًا: مطابقة ألوان علامتك، وإعداد نماذج ما قبل الدردشة لجمع بيانات الزوار، وضبط مؤشرات الكتابة، وتفعيل الإدخال الصوتي وغيرها. للتثبيت، راجع دليل قناة الموقع.

جلب إعداد Widget

نطاق الصلاحيات: 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 سلسلة نصية	رسالة الترحيب الرئيسية عند فتح 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، وتظهر في ترويسة الدردشة وكأيقونة الفقاعة العائمة. ارفعها عبر PATCH بصيغة base64. تعني null حذف الصورة وعدم عرض صورة رمزية في Widget
bubble_icon_image سلسلة نصية أو null	مهمل. يطابق avatar_image دائمًا؛ فأيقونة الفقاعة وصورة الدردشة أصبحتا صورة واحدة (راجع توحيد الصورة الرمزية لوكيل AI)
default_avatar_image سلسلة نصية	للقراءة فقط. رابط الصورة الرمزية الافتراضية لوكيل 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) هي نسبة تلوين الزجاج، ولا يعرضها 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 قيمة منطقية	إزالة علامة “Powered by Quickchat” من Widget

نموذج ما قبل الدردشة

الحقل	الوصف
prechat_active قيمة منطقية	تفعيل نموذج ما قبل الدردشة. عند تفعيله، يجب على الزوار تعبئته قبل الدردشة
prechat_header_text سلسلة نصية أو null	نص ترويسة نموذج ما قبل الدردشة
prechat_button_text سلسلة نصية أو null	تسمية زر إرسال نموذج ما قبل الدردشة
prechat_message_text سلسلة نصية أو null	النص أو التعليمات المعروضة في نموذج ما قبل الدردشة (HTML)

تحديث إعداد Widget

نطاق الصلاحيات: write_all

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

جسم الطلب: كل الحقول اختيارية. أدرج فقط ما تريد تحديثه.

ملاحظة

لـ avatar_image، أرسل بيانات صورة مشفرة بـ base64 (5 MB كحد أقصى). تعيد الاستجابة رابط الصورة المخزنة. يحذف إرسال avatar_image: null الصورة الرمزية (فلا يعرض Widget صورة)، ويعيد use_default_avatar: true الصورة الرمزية الافتراضية لوكيل AI.

توحيد الصورة الرمزية لوكيل AI

دُمجت صورة الدردشة (شعار الترويسة) وأيقونة الفقاعة العائمة (المشغّل) في صورة واحدة، هي الصورة الرمزية لوكيل AI، المخزنة في avatar_image. تطابقها أيقونة الفقاعة دائمًا؛ لم تعد هناك صورة مستقلة للمشغّل. إذا كنت تتكامل مباشرة مع هذه النقطة، انتبه لتغييرات السلوك التالية:

• الرفع عبر bubble_icon_image مهمل: يضبط الآن الصورة الرمزية الموحدة لوكيل AI، مما يستبدل أيضًا الصورة في ترويسة الدردشة. استخدم avatar_image بدلًا منه.
• bubble_icon_image: null لا ينفذ شيئًا. كان يمسح أيقونة المشغّل؛ وبما أن المشغّل يطابق الصورة الرمزية، احذف عبر avatar_image: null بدلًا منه.
• الوكلاء الذين لم يخصصوا الصورة الرمزية يعرضون الصورة الافتراضية لوكيل 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: تعيد إعداد Widget المحدّث (المخطط نفسه كما في استجابة جلب إعداد Widget).

---