# Chat API
SUMMARY: دردشة غير متزامنة بين البشر ووكلاء LLM — الاستطلاع، الرد، السجل، عدد الرسائل غير المقروءة، رفع الملفات.

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

Chat API
تُمكّن Chat API المراسلة غير المتزامنة بين البشر ووكلاء LLM. على عكس الدردشة
المتزامنة (بنمط ChatGPT)، يمكن للإنسان ترك رسائل بينما يعمل الوكيل — يستطلع
الوكيل بين استدعاءات الأدوات.
كيفية العمل
[CODE BLOCK]
1. يُرسل الإنسان رسالة عبر واجهة الويب (يستخدم JWT)
2. تُخزّن الرسالة وتُعلّم كغير مقروءة
3. يستطلع الوكيل عبر  بين استدعاءات الأدوات
4. يُرجع الاستطلاع جميع الرسائل غير المقروءة ويُعلّمها كمقروءة
5. يعالج الوكيل الرسالة، ويرد اختياريًا عبر 
نقاط النهاية
GET /chat/poll
الاستطلاع للرسائل الجديدة من الإنسان. يُرجع الرسائل غير المقروءة ويُعلّمها
كمقروءة. استخدم هذا بين استدعاءات الأدوات.
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
POST /chat/reply
إرسال رسالة باعتبارك الوكيل.
[CODE BLOCK]
POST /chat/send
إرسال رسالة باعتبارك الإنسان (يتطلب JWT، وليس Mind Key).
[CODE BLOCK]
GET /chat/history
الحصول على سجل الدردشة الأخير (كلا الطرفين).
[CODE BLOCK]
GET /chat/unread
الحصول على عدد الرسائل غير المقروءة.
[CODE BLOCK]
GET /chat/status
الحصول على حالة جلسة الدردشة (طوابع زمنية لآخر رسالة، عدد الرسائل غير المقروءة).
[CODE BLOCK]
POST /chat/upload
رفع مرفق ملف لرسالة محددة (نموذج multipart).
[CODE BLOCK]
GET /chat/files/:messageid
قائمة مرفقات الملفات لرسالة.
[CODE BLOCK]
GET /chat/file/:fileid
تنزيل مرفق ملف.
[CODE BLOCK]
نمط الاستطلاع
> [!TIP]
> استطلع كل 30-60 ثانية بين استدعاءات الأدوات. لا تستطلع بشكل أكثر تكرارًا —
> فهذا يهدر حصة الـ API ولا يقدم أي فائدة.
[CODE BLOCK]
الخطوات التالية
- Tasks API
- نمط استطلاع الدردشة