نظرة عامة

توفر Quickchat AI واجهة REST API للوصول البرمجي إلى إعداد وكيل AI وقاعدة المعرفة والمحادثات وإجراءات AI وغيرها.

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

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

• تحقق من اتصال MCP نموذجي. ابدأ الاتصال واسرد الأدوات على نقطة وثائق Cloudflare أو Microsoft Learn فقط. لا يُجرى تسجيل دخول أو تنفيذ أدوات.

المصادقة

تستخدم جميع نقاط API مصادقة رمز Bearer. أدرج رمز API في رأس Authorization لكل طلب:

Authorization: Bearer <API_TOKEN>

تُنشأ الرموز في لوحة تحكم Quickchat تحت التطبيقات الخارجية > API. كل رمز هو JWT يتضمن scenario_id، لذا لا يلزم رأس معرف إضافي.

• صلاحية الرمز: 52 أسبوعًا من الإنشاء
• يمكن إلغاء الرموز في أي وقت من لوحة التحكم
• نطاق كل رمز مقصور على وكيل AI واحد (سيناريو)
• يتطلب إنشاء الرموز خطة Business أو أعلى؛ يُعطل الخيار في الخطط الأدنى وتعيد النقطة 402 Payment Required

ملاحظة

تقبل نقطة الدردشة الفورية (POST https://app.quickchat.ai/chat) رمز Bearer نفسه المستخدم في بقية API، لكنها تقع خارج المسار الأساسي /v1/api/ وتتطلب scenario_id في جسم الطلب. راجع صفحة الدردشة للمرجع الكامل.

نطاقات الرموز

تُنشأ رموز API بأحد نطاقين:

النطاق	مستوى الوصول	الوصف
read_all	قراءة فقط	يقرأ كل الموارد دون إنشاء أو تحديث أو حذف
write_all	قراءة وكتابة	وصول كامل إلى جميع النقاط، بما فيها عمليات الكتابة

• يُعين نطاق الرمز عند إنشائه في لوحة التحكم تحت التطبيقات الخارجية > API
• يتضمن نطاق write_all جميع أذونات read_all تلقائيًا
• استخدام رمز read_all مع نقطة كتابة يعيد 403 مع "Insufficient token scope. Required: write_all"

نصيحة

استخدم رموز read_all للمراقبة والتحليلات وتكاملات القراءة فقط. لا تستخدم write_all إلا عندما يحتاج تكاملك إلى إنشاء موارد أو تعديلها.

متطلبات النطاق حسب مجموعة النقاط:

مجموعة النقاط	عمليات القراءة	عمليات الكتابة
إعدادات روبوت الدردشة	read_all	write_all
إعدادات قاعدة المعرفة	read_all	write_all
المقالات	read_all	write_all
روابط المقالات حسب اللغة	read_all	write_all
الوسوم	read_all	-
رفع الملفات	-	write_all
استيراد المحتوى الخارجي	-	write_all
قاعدة معرفة Intercom	read_all	write_all
إعداد Widget	read_all	write_all
المحادثات	read_all	-
البيانات الوصفية للمحادثة	read_all	write_all
إعداد التحويل	read_all	write_all
تقييم المحادثة	read_all	write_all
إجراءات AI	read_all	write_all

عنوان URL الأساسي

مجموعة النقاط	عنوان URL الأساسي
قاعدة المعرفة وإجراءات AI ورفع الملفات والاستيراد وإعدادات روبوت الدردشة وWidget والتحويل وتقييم المحادثة	https://app.quickchat.ai/v1/api/
المحادثات	https://app.quickchat.ai/v1/api_core/
الدردشة الفورية	https://app.quickchat.ai/chat

حدود المعدل

تُطبق حدود المعدل لكل رمز ولكل نقطة.

الفئة	الحد	ينطبق على
READ	120 طلبًا/دقيقة	عمليات GET والسرد
WRITE	60 طلبًا/دقيقة	POST وPATCH وPUT وDELETE
HEAVY	20 طلبًا/دقيقة	رفع الملفات والاستيراد واستخراج محتوى الويب

عند تجاوز حد المعدل، تعيد API حالة HTTP 429 Too Many Requests.

Webhooks

لا ترسل Quickchat AI طلبات webhook صادرة. لا توجد طريقة للاشتراك في حدث ليُرسل طلب POST إلى نقطتك عند وصول رسالة أو تحويل محادثة أو إغلاقها.

تخدم البدائل المتاحة أغراضًا مختلفة:

• إجراءات AI تستدعي API الخاص بك أثناء المحادثة. توفر إجراءات API أوضاع يقرر AI وقبل أول رد وعند تطابق البيانات الوصفية. تحاول الأوضاع التلقائية الاتصال مرة واحدة لكل محادثة وفق شروطها الموثقة؛ وليست اشتراكات في كل رسالة أو تحويل. استخدمها لمهام مثل تسجيل عميل محتمل أو إخطار نظامك عند توفر البيانات المطلوبة.
• Google Sheets يضيف صفًا عند تشغيل إجرائه. لا يسجل كل رسالة أو تحويل تلقائيًا.
• استطلاع API المحادثات يجلب المحادثات المخزنة وأحداثها، بما فيها الرسائل وأي علامات تحويل مسجلة. اتبع تقسيم الصفحات وحد READ أعلاه. يضيف الاستطلاع تأخيرًا؛ وقد تفوت مقارنة حالة المحادثة بين الاستطلاعات تغييرات وسيطة. لا تفترض أنه يقدم سجلًا شاملًا لكل انتقال في التحويل أو الإسناد.

يتطلب الوصول إلى API خطة Business؛ راجع الخطط والحدود.

تقسيم الصفحات

تدعم نقاط السرد تقسيم الصفحات عبر معلمات الاستعلام:

المعلمة	الوصف
limit عدد صحيح	عدد العناصر في الصفحة
offset عدد صحيح	عدد العناصر المتجاوزة

تتبع الاستجابات المقسمة إلى صفحات هذه البنية:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

معالجة الأخطاء

تُعاد جميع الأخطاء بصيغة JSON التالية:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

الحالة	الرمز	الوصف
400	BAD_REQUEST	إدخال غير صالح أو حقول مطلوبة مفقودة
401	PERMISSION_DENIED	رمز غير صالح أو منتهي الصلاحية أو ملغى
402	PAYMENT_REQUIRED	يلزم اشتراك نشط
403	PERMISSION_DENIED	لا يملك الرمز النطاق المطلوب للعملية
404	NOT_FOUND	المورد غير موجود
409	CONFLICT	عملية متعارضة (مثل تعديل متزامن)
422	VALIDATION_ERROR	فشل التحقق من جسم الطلب وفق المخطط
429	TOO_MANY_REQUESTS	تجاوز حد المعدل
500	UNKNOWN	خطأ داخلي في الخادم
503	SERVICE_UNAVAILABLE	عدم توفر مؤقت

---