البيانات الوصفية للمحادثة

تتيح البيانات الوصفية للمحادثة إرفاق بيانات مخصصة بصيغة مفتاح وقيمة بالمحادثات، لتنشئ صلة قوية بين أنظمتك ووكيل AI. تنتقل البيانات الوصفية عبر سير عمل Quickchat بالكامل:

• الإرسال عبر API: استخدم هذه النقاط لإرفاق بيانات وصفية بأي محادثة برمجيًا (مثلًا من CRM أو نظام الدعم أو الخادم الخلفي)
• الإرسال عبر Widget أو التضمين: مرّر البيانات الوصفية كمعلمات تهيئة عند تحميل Widget، أو أضفها ديناميكيًا أثناء محادثة نشطة باستخدام JavaScript SDK
• الظهور في لوحة التحكم: تظهر البيانات الوصفية المخصصة في تفاصيل المحادثة بصندوق الوارد. تُصفى المفاتيح الداخلية، وتُعرض بيانات الاتصال الملتقطة وذاكرة الإجراءات بصورة خاصة
• التضمين في التصدير: تُدرج البيانات الوصفية عند تصدير المحادثات من لوحة التحكم، لتتاح للتحليل دون اتصال
• الاستخدام في إجراءات AI: يمكن إدراج قيم البيانات الوصفية مباشرة كعناصر نائبة {{metadata_<key>}} في إجراءات AI. راجع متغيرات إجراءات AI للمرجع الكامل للعناصر النائبة المتاحة
• الإتاحة لوكيل AI عند السماح: يستخدم سياق النموذج مجموعة مصفاة من البيانات الوصفية. تخزين مفتاح لا يضمن أن يتلقاه النموذج أو يذكره

استخدم البيانات الوصفية لمراجع العملاء وسياق الحساب والتحليلات ومدخلات الإجراءات. التخزين والعرض في صندوق الوارد والاستبدال في الإجراءات وسياق النموذج استخدامات منفصلة للبيانات نفسها.

تُتحقق البيانات الوصفية وفق مخطط JSON إذا ضُبط أحدها في لوحة التحكم.

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

• عاين مفاتيح البيانات الوصفية. تحقق من تحويل أسماء الحقول المقدمة إلى مفاتيح متغيرات، بما فيها الأسماء المكررة وأخطاء المفاتيح المحجوزة. لا يفحص ذلك القيم أو الأذونات الخاصة بالحساب.

• تحقق من شروط تشغيل الإجراء. قيّم الشروط باستخدام بيانات وصفية نموذجية مقدمة دون تشغيل إجراء.

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

سياق النموذج والتفويض

في القنوات التي يتحكم بها الزائر مثل Widget الموقع والتضمين، يقبل سياق النموذج مفاتيح اتصال الزائر (visitor_name وvisitor_email وvisitor_phone_number) والمفاتيح المؤهلة التي تشير إليها الإجراءات النشطة أو تلتقطها. تُصفى القيم الداخلية والمحجوزة، وتُطبق أيضًا حدود الإعداد والحجم. للتكاملات الأخرى قواعد سياق خاصة بالقناة. لا يصبح مفتاح مخصص مثل customer_tier أو customer_id مرئيًا للنموذج تلقائيًا لمجرد إرساله.

يمكن للإجراء استبدال {{metadata_<key>}} عند بناء طلبه دون مطالبة AI بتوليد تلك القيمة. لا يجعل ذلك البيانات الوصفية العادية سرية: فقد تدخل قيمة مؤهلة سياق النموذج بصورة مستقلة أو تظهر في استجابة إجراء. لا تخزن مفاتيح API أو كلمات المرور في البيانات الوصفية المخصصة.

البيانات الوصفية التي يقدمها المتصفح ليست دليلًا على الهوية أو الإذن. يجب أن تصادق خدمتك المستقبلة على الوصول إلى السجلات الخاصة وتفوضه؛ لا يكفي معرف عميل أو مستوى خطة يرسله المتصفح. اختبر طلب الإجراء الناتج ورد الوكيل لإعدادك.

جلب البيانات الوصفية

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

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

الاستجابة 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

تعيين البيانات الوصفية

أنشئ البيانات الوصفية لمحادثة أو حدّثها.

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

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

جسم الطلب

المعلمة	الوصف
metadata كائن، مطلوب	البيانات الوصفية المراد تخزينها بصيغة مفتاح وقيمة

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

الاستجابة 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---