إعداد التحويل

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

كيف يعمل التحويل التلقائي:

1. أثناء المحادثة، يقيّم AI كل رسالة وفق الإرشادات العامة (مثل إحباط المستخدم أو نقص المعرفة) والإرشادات المخصصة التي تحددها
2. عندما تتحقق قاعدة، يعرض AI للزائر رسالة تأكيد تسأله إن كان يريد التحدث إلى شخص
3. إذا أكد الزائر، تُنقل المحادثة إلى موظف، مع ملخص اختياري يولده AI لما دار حتى الآن
4. إذا ضُبطت ساعات العمل وكان الطلب خارجها، تُعرض رسالة مخصصة بدلًا من ذلك

طرق تحويل إضافية:

• محفزات الكلمات المفتاحية: يستطيع الزائر كتابة عبارات محددة (مثل “التحدث إلى شخص” أو “موظف”) لطلب التحويل مباشرة
• التحويل اليدوي من لوحة التحكم: يستطيع الموظفون تولي أي محادثة من صندوق الوارد بتغيير الشخص المسندة إليه

يتيح التوجيه حسب الموضوع لـ AI إسناد التحويل إلى زميل واحد بناءً على وصف التوجيه الخاص به. ينتمي كل ملف إلى مستخدم واحد، وهو منفصل عن فئات المواضيع في التحليلات. اضبط الملفات عبر routing_profiles في طلب PUT. الإسناد ومستلمو إشعارات البريد إعدادان منفصلان.

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

• عاين طلب إجراء API. اعرض قالب طلب مقدمًا بقيم نموذجية اصطناعية دون إرساله. لا تدرج رؤوس بيانات الاعتماد.

• تحقق من مجموعة بيانات اختبار. افحص مجموعة صغيرة مقدمة وفق التنسيق المدعوم دون تشغيل وكيل AI.

جلب إعداد التحويل

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

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

Shell

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

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

الاستجابة 200 OK

تحتوي الاستجابة عدة كائنات متداخلة:

settings: إعداد التحويل الأساسي:

الحقل	الوصف
is_active قيمة منطقية	هل التحويل إلى موظف مفعّل
keywords مصفوفة سلاسل نصية	كلمات مفتاحية تشغّل التحويل (مثل ["speak to human", "agent"])
ai_summary_active قيمة منطقية	إرسال ملخص للمحادثة يولده AI إلى الموظف عند التحويل
topic_based_routing_active قيمة منطقية	هل التوجيه حسب الموضوع إلى موظفين محددين مفعّل (للقراءة فقط، يُضبط عبر ملفات التوجيه)
question_message سلسلة نصية	رسالة تسأل الزائر إن كان يريد الاتصال بشخص
confirmation_message سلسلة نصية	الرسالة المعروضة بعد تأكيد الزائر للتحويل (500 حرف كحد أقصى)
confirmation_outside_working_hours_message سلسلة نصية	الرسالة المعروضة عند طلب التحويل خارج ساعات العمل (500 حرف كحد أقصى)
working_hours_active قيمة منطقية	قصر التحويل على ساعات العمل
timezone سلسلة نصية	المنطقة الزمنية لساعات العمل (مثل "Europe/London")
send_email_notification قيمة منطقية	إرسال إشعارات بريد إلى الموظفين عند التحويل
emails مصفوفة سلاسل نصية	عناوين البريد التي تتلقى الإشعارات

availability: جدول ساعات العمل (مصفوفة فترات):

الحقل	الوصف
id عدد صحيح	معرف فترة التوفر
day_span سلسلة نصية	يوم أو نطاق أيام (مثل "monday" أو "monday-friday")
start_time سلسلة نصية	وقت البدء بصيغة "HH:MM"
end_time سلسلة نصية	وقت الانتهاء بصيغة "HH:MM"

generic_guidelines: قواعد تشغيل التحويل المحددة مسبقًا (مصفوفة):

الحقل	الوصف
name سلسلة نصية	نوع الإرشاد: "user_frustration" أو "customer_support_suggestion" أو "lack_of_knowledge" أو "irrelevant_advice" أو "media_message"
description سلسلة نصية	وصف وقت تفعيل الإرشاد
is_active قيمة منطقية	هل هذا الإرشاد مفعّل

custom_guidelines: قواعد تشغيل التحويل التي يحددها المستخدم (مصفوفة):

الحقل	الوصف
id عدد صحيح	معرف الإرشاد
name سلسلة نصية	اسم الإرشاد المخصص (100 حرف كحد أقصى)
description سلسلة نصية	متى ينبغي أن يشغّل الإرشاد التحويل (2000 حرف كحد أقصى)
is_active قيمة منطقية	هل هذا الإرشاد مفعّل

routing_profiles: يوجه التوجيه حسب الموضوع التحويلات إلى الموظفين المناسبين بناءً على موضوع المحادثة.

عندما يبدأ AI التحويل، يمكنه اختيار زميل من ملفات التوجيه النشطة. تُسند المحادثة إليه إذا كان الاختيار صالحًا، وإلا تبقى غير مسندة. قد تتركها محفزات التحويل الأخرى غير مسندة أيضًا. تستخدم إشعارات البريد settings.send_email_notification وsettings.emails بصورة مستقلة عن اختيار التوجيه.

مثال: أعطِ زميل المالية وصف التوجيه “أسئلة الفوترة والفواتير”، والمهندس “الدعم التقني”. عند سؤال عن فاتورة، يستطيع AI إسناد التحويل إلى زميل المالية. لا تتغير قائمة مستلمي البريد المضبوطة بسبب هذا الإسناد.

اضبط الملفات تحت الإجراءات وMCP > التحويل إلى موظف > تعديل الإجراء > التوجيه حسب الموضوع، أو عبر طلب PUT.

الحقل	الوصف
user_id عدد صحيح	معرف مستخدم الزميل؛ يجب أن يملك وصولًا إلى وكيل AI هذا
routing_description سلسلة نصية	المحادثات التي ينبغي للزميل معالجتها (150 حرفًا كحد أقصى؛ لا يجوز أن يكون فارغًا عند التفعيل)
is_active قيمة منطقية	هل ملف التوجيه مفعّل
email, first_name, last_name سلاسل نصية	بيانات المستخدم التي يعيدها GET؛ غير مطلوبة في PUT

تحديث إعداد التحويل

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

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

تنبيه

يستبدل PUT إعداد التحويل كاملًا كوحدة واحدة. أدرج settings وavailability وgeneric_guidelines وcustom_guidelines. أدرج routing_profiles للحفاظ على التوجيه: حذفه يعادل قائمة فارغة ويزيل الملفات الموجودة. لإجراء تغييرات جزئية، اجلب الإعداد الحالي أولًا بـ GET، وعدّل الحقول اللازمة، ثم أعد الكائن كاملًا بـ PUT. يستخدم كل ملف توجيه user_id وrouting_description وis_active.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

الاستجابة 200 OK: تعيد إعداد التحويل المحدّث.

---