الدردشة

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

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

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

الدردشة

ترسل نقطة الدردشة الفورية رسالة زائر إلى وكيل AI وتعيد رد AI في رحلة طلب واحدة. هذه هي النقطة المناسبة عند بناء واجهة دردشة مخصصة فوق Quickchat AI.

تختلف عن النقاط الأخرى في أمرين: تقع عند app.quickchat.ai/chat خارج المسارين الأساسيين /v1/api/ و/v1/api_core/، وتقرأ scenario_id من جسم الطلب بدلًا من الرمز. تستخدم مصادقة Bearer نفسها المستخدمة في بقية API.

ملاحظة

أرسل كل طلب إلى https://app.quickchat.ai/chat. يجب أن يطابق scenario_id في الجسم وكيل AI المرتبط برمز Bearer.

إرسال رسالة

POST https://app.quickchat.ai/chat

جسم الطلب

المعلمة	الوصف
scenario_id سلسلة نصية، مطلوبة	معرف وكيل AI. يجب أن يطابق scenario_id المرتبط برمز Bearer
text سلسلة نصية، مطلوبة	رسالة إدخال المستخدم
conv_id سلسلة نصية	معرف المحادثة. احذفه في الطلب الأول لبدء محادثة جديدة، ثم أعد تمرير conv_id المعاد في الطلبات التالية لمتابعتها
client_metadata كائن	أزواج مفتاح وقيمة مخصصة (نوصي بخمسة مفاتيح كحد أقصى) تُرفق بكل رسالة. تظهر كأعمدة بيانات في تصدير المحادثة بصندوق الوارد

يبدأ الطلب دون conv_id محادثة جديدة، ويُعاد conv_id المُنشأ في الاستجابة. خزن conv_id وأرسله مجددًا في الطلبات اللاحقة للحفاظ على سياق المحادثة عبر تفاعلات المستخدم المتعددة.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

الاستجابة 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

الحقل	الوصف
conv_id سلسلة نصية	معرف المحادثة. يُعاد دائمًا. أعد تمريره في حقل الجسم conv_id لمتابعة المحادثة
reply سلسلة نصية	استجابة وكيل AI. قد تحتوي HTML مثل فواصل الأسطر <br>
ord_number عدد صحيح	رقم الرسالة التسلسلي داخل المحادثة
src عدد صحيح	مؤشر مصدر داخلي. يمكن لعملاء API تجاهل الحقل

لمتابعة محادثة موجودة، أعد تمرير conv_id الذي تلقيته:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

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

تقبل نقطة الدردشة معلمة client_metadata اختيارية: سمات مخصصة تُعين لكل رسالة جديدة وتظهر كأعمدة بيانات في تصدير المحادثة بصندوق الوارد. يمكنك إرفاق السمات نفسها عبر Widget. نوصي بإرسال خمسة مفاتيح كحد أقصى في المرة، مثل {"userId": 12, "website": "mywebsite.com"}. هذه توصية وليست حدًا تفرضه API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

تصفية قاعدة المعرفة بالوسوم

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

للتصفية بوسم، أضف مفتاح kb_topic إلى client_metadata. يجب أن يوجد kb_topic في كل طلب بالمحادثة، بما فيه الطلب الذي يبدأها. يمكن أن تتغير قيمته بين الطلبات، لكن يجب أن يوجد المفتاح طوال المحادثة لتطبيق المرشح.

في المثال أدناه، تُدرج أي مقالة موسومة بـ your-topic أو دون أي وسم ضمن مجموعة المعرفة المرشحة للرد.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

الأخطاء

تعيد نقطة الدردشة رسالة خطأ بنص عادي مع رمز حالة HTTP مناسب.

الحالة	الوصف	الإجراء
400	scenario_id مفقود أو لم تُقدم بيانات اعتماد	أدرج scenario_id في الجسم ورأس Authorization: Bearer <API_TOKEN> صالحًا
400	conv_id غير صالح (Conversation conv_id <id> is not valid.)	احذف conv_id لبدء محادثة جديدة، أو مرّر conv_id أعادته استجابة سابقة
401	بيانات اعتماد غير صالحة (Unauthorized.)	تحقق من صلاحية رمز Bearer أو مفتاح API لهذا scenario_id
404	scenario_id غير معروف (No implementation found for scenario_id <id>)	تحقق من scenario_id ومن ارتباط رمز Bearer به
500	خطأ داخلي في الخادم	مشكلة من جانبنا. يُرجى التواصل مع الدعم
503	الخدمة غير متاحة	الخوادم محملة مؤقتًا أو تحت الصيانة. إذا استمرت المشكلة، يُرجى التواصل مع الدعم