مرجع واجهة برمجة تطبيقات الدردشة

المصادقة

تتم مصادقة كل طلب باستخدام مفتاح واجهة برمجة التطبيقات لمساحة عملك، ويُرسَل في ترويسة X-API-Key (أو كمعامل api_key). تبدو المفاتيح بالشكل ck_live_.... تعامل مع المفتاح كأنه كلمة مرور - أي شخص يمتلكه يمكنه إرسال رسائل تُحتسب على مساحة عملك. يمكنك تدويره في أي وقت من الإعدادات -> الوصول إلى واجهة برمجة التطبيقات؛ يتوقف المفتاح السابق عن العمل على الفور.

إرسال رسالة

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

المعاملات:

• message (سلسلة نصية) - رسالة الزائر. مطلوب ما لم تُرفق files.
• ticket_id (سلسلة نصية، اختياري) - متابعة محادثة قائمة. احذفه لبدء محادثة جديدة.
• visitor_email / visitor_name (سلسلة نصية، اختياري) - إرفاق تفاصيل الاتصال بالتذكرة.
• files (متعدد الأجزاء، اختياري) - مرفقات الزائر. يتطلب خطة تدعم رفع الملفات.

الاستجابة

يعيد الاستدعاء 202 Accepted بمجرد تخزين الرسالة؛ يتم إنشاء رد الذكاء الاصطناعي بشكل غير متزامن.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

مرّر data.ticket_id مجددًا كقيمة ticket_id في الاستدعاء التالي لإبقاء المحادثة مستمرة. لتلقي رد الذكاء الاصطناعي، اشترك عبر WebSocket (ActionCable) في القناة المرتبطة بـ data.id - وهو نفس تجزئة الزائر التي تستخدمها الأداة المضمّنة.

قراءة المحادثات

اجلب التذاكر ورسائلها باستخدام نفس X-API-Key. كل نقطة نهاية للقراءة مقيدة بمساحة عملك ومتاحة في خطة Business.

• GET /api/v1/chat/tickets - سرد التذاكر، الأحدث أولاً. معاملات الاستعلام: status وlimit (بحد أقصى 100) وoffset. تُرجع tickets وpagination.
• GET /api/v1/chat/tickets/:id - تذكرة واحدة.
• GET /api/v1/chat/tickets/:id/messages - رسائل التذكرة بالترتيب، كل رسالة تحتوي على role وcontent وattachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

حدود المعدل والحصة

يتم تقييد الطلبات إلى نحو 20 طلبًا في الدقيقة لكل مفتاح (ولكل عنوان IP). كما يستهلك كل رد يتم إنشاؤه من حصة الرسائل الشهرية في خطتك؛ وبمجرد نفادها تعيد نقطة النهاية 200 مع data.limit_reached: true بدلاً من إنشاء رد.

الأخطاء

• 401 - لم يتم تقديم أي مفتاح لواجهة برمجة التطبيقات.
• 404 - المفتاح لا يطابق أي مساحة عمل (مثلاً بعد التدوير).
• 403 plan_upgrade_required - مساحة العمل ليست على خطة Business.
• 403 - الاشتراك غير نشط، أو أن الطلب جاء من نطاق غير مسموح به في إعدادات الأداة.
• 422 - الرسالة مفقودة (ولم تُرفق أي ملفات).