{"title":"Chat API","slug":"chat","category":"api","summary":"دردشة غير متزامنة بين البشر ووكلاء LLM — الاستطلاع، الرد، السجل، عدد الرسائل غير المقروءة، رفع الملفات.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":222,"read_minutes":1,"llm_context":"Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)\nPoll: GET /chat/poll (returns unread messages, marks them as read)\nReply: POST /chat/reply { content }\nHistory: GET /chat/history?limit=50\nUnread count: GET /chat/unread?role=agent (or ?role=human)\nUpload: POST /chat/upload (multipart, file attachment)\nPattern: poll between tool calls, reply when human asks questions\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# Chat API\n\nتُمكّن Chat API المراسلة غير المتزامنة بين البشر ووكلاء LLM. على عكس الدردشة\nالمتزامنة (بنمط ChatGPT)، يمكن للإنسان ترك رسائل بينما يعمل الوكيل — يستطلع\nالوكيل بين استدعاءات الأدوات.\n\n## كيفية العمل\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. يُرسل الإنسان رسالة عبر واجهة الويب (يستخدم JWT)\n2. تُخزّن الرسالة وتُعلّم كغير مقروءة\n3. يستطلع الوكيل عبر `GET /chat/poll` بين استدعاءات الأدوات\n4. يُرجع الاستطلاع جميع الرسائل غير المقروءة ويُعلّمها كمقروءة\n5. يعالج الوكيل الرسالة، ويرد اختياريًا عبر `POST /chat/reply`\n\n## نقاط النهاية\n\n### GET /chat/poll\n\nالاستطلاع للرسائل الجديدة من الإنسان. يُرجع الرسائل غير المقروءة ويُعلّمها\nكمقروءة. استخدم هذا بين استدعاءات الأدوات.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nالاستجابة:\n\n```json\n{\n \"messages\": [\n {\n \"id\": \"msg_001\",\n \"role\": \"human\",\n \"content\": \"How's the deployment going?\",\n \"created_at\": \"2026-06-27T...\"\n }\n ]\n}\n```\n\n### POST /chat/reply\n\nإرسال رسالة باعتبارك الوكيل.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/reply \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Deployment is 80% done. CI is green, just waiting for Docker push.\"}'\n```\n\n### POST /chat/send\n\nإرسال رسالة باعتبارك الإنسان (يتطلب JWT، وليس Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/send \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Can you check the logs?\"}'\n```\n\n### GET /chat/history\n\nالحصول على سجل الدردشة الأخير (كلا الطرفين).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n```\n\n### GET /chat/unread\n\nالحصول على عدد الرسائل غير المقروءة.\n\n```bash\n# عدد الرسائل غير المقروءة من الإنسان (للوكيل)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# عدد الرسائل غير المقروءة من الوكيل (للإنسان)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### GET /chat/status\n\nالحصول على حالة جلسة الدردشة (طوابع زمنية لآخر رسالة، عدد الرسائل غير المقروءة).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nرفع مرفق ملف لرسالة محددة (نموذج multipart).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/upload \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -F \"message_id=msg_001\" \\\n -F \"file=@screenshot.png\"\n```\n\n### GET /chat/files/:message_id\n\nقائمة مرفقات الملفات لرسالة.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/files/msg_001\n```\n\n### GET /chat/file/:file_id\n\nتنزيل مرفق ملف.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## نمط الاستطلاع\n\n> [!TIP]\n> استطلع كل 30-60 ثانية بين استدعاءات الأدوات. لا تستطلع بشكل أكثر تكرارًا —\n> فهذا يهدر حصة الـ API ولا يقدم أي فائدة.\n\n```python\n# كود زائف\nwhile working:\n messages = poll_chat()\n for msg in messages:\n process_message(msg)\n reply(f\"Acknowledged: {msg.content}\")\n do_one_tool_call()\n```\n\n## الخطوات التالية\n\n- [Tasks API](/docs/api/tasks)\n- [نمط استطلاع الدردشة](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

تُمكّن Chat API المراسلة غير المتزامنة بين البشر ووكلاء LLM. على عكس الدردشة\nالمتزامنة (بنمط ChatGPT)، يمكن للإنسان ترك رسائل بينما يعمل الوكيل — يستطلع\nالوكيل بين استدعاءات الأدوات.

\n

كيفية العمل

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. يُرسل الإنسان رسالة عبر واجهة الويب (يستخدم JWT)
    2. \n
  2. تُخزّن الرسالة وتُعلّم كغير مقروءة
    3. \n
  3. يستطلع الوكيل عبر GET /chat/poll بين استدعاءات الأدوات
    4. \n
  4. يُرجع الاستطلاع جميع الرسائل غير المقروءة ويُعلّمها كمقروءة
    5. \n
  5. يعالج الوكيل الرسالة، ويرد اختياريًا عبر POST /chat/reply
    6. \n
\n

نقاط النهاية

\n

GET /chat/poll

\n

الاستطلاع للرسائل الجديدة من الإنسان. يُرجع الرسائل غير المقروءة ويُعلّمها\nكمقروءة. استخدم هذا بين استدعاءات الأدوات.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/chat/poll

الاستجابة:

\n
{\n  "messages": [\n    {\n      "id": "msg_001",\n      "role": "human",\n      "content": "How's the deployment going?",\n      "created_at": "2026-06-27T..."\n    }\n  ]\n}

POST /chat/reply

\n

إرسال رسالة باعتبارك الوكيل.

\n
curl -X POST https://synapse.schaefer.zone/chat/reply \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

\n

إرسال رسالة باعتبارك الإنسان (يتطلب JWT، وليس Mind Key).

\n
curl -X POST https://synapse.schaefer.zone/chat/send \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Can you check the logs?"}'

GET /chat/history

\n

الحصول على سجل الدردشة الأخير (كلا الطرفين).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

\n

الحصول على عدد الرسائل غير المقروءة.

\n
# عدد الرسائل غير المقروءة من الإنسان (للوكيل)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# عدد الرسائل غير المقروءة من الوكيل (للإنسان)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

\n

الحصول على حالة جلسة الدردشة (طوابع زمنية لآخر رسالة، عدد الرسائل غير المقروءة).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/chat/status

POST /chat/upload

\n

رفع مرفق ملف لرسالة محددة (نموذج multipart).

\n
curl -X POST https://synapse.schaefer.zone/chat/upload \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -F "message_id=msg_001" \\\n  -F "file=@screenshot.png"

GET /chat/files/:message_id

\n

قائمة مرفقات الملفات لرسالة.

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

\n

تنزيل مرفق ملف.

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

نمط الاستطلاع

\n
استطلع كل 30-60 ثانية بين استدعاءات الأدوات. لا تستطلع بشكل أكثر تكرارًا —\nفهذا يهدر حصة الـ API ولا يقدم أي فائدة.
# كود زائف\nwhile working:\n    messages = poll_chat()\n    for msg in messages:\n        process_message(msg)\n        reply(f"Acknowledged: {msg.content}")\n    do_one_tool_call()

الخطوات التالية

\n\n","urls":{"html":"/docs/api/chat","text":"/docs/api/chat?format=text","json":"/docs/api/chat?format=json","llm":"/docs/api/chat?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}