{"title":"Chat API","slug":"chat","category":"api","summary":"मानव और LLM एजेंट्स के बीच अतुल्यकालिक चैट — poll, reply, history, अपठित गिनती, फ़ाइल अपलोड।","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":295,"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":"hi","translated":true,"requested_lang":"hi","content_markdown":"\n# Chat API\n\nChat API मानव और LLM एजेंट्स के बीच अतुल्यकालिक मैसेजिंग सक्षम करता है। तुल्यकालिक चैट (ChatGPT-शैली) के विपरीत, मानव एजेंट के काम कर रहे होने पर भी संदेश छोड़ सकता है — एजेंट टूल कॉल्स के बीच poll करता है।\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. मानव वेब UI के माध्यम से संदेश भेजता है (JWT का उपयोग करता है)\n2. संदेश स्टोर किया जाता है, अपठित के रूप में चिह्नित किया जाता है\n3. एजेंट टूल कॉल्स के बीच `GET /chat/poll` कॉल करता है\n4. Poll सभी अपठित संदेश लौटाता है और उन्हें पठित के रूप में चिह्नित करता है\n5. एजेंट संदेश को प्रोसेस करता है, वैकल्पिक रूप से `POST /chat/reply` के माध्यम से उत्तर देता है\n\n## एंडपॉइंट्स\n\n### GET /chat/poll\n\nमानव के नए संदेशों के लिए poll करें। अपठित संदेश लौटाता है और उन्हें पठित के रूप में चिह्नित करता है। इसे टूल कॉल्स के बीच उपयोग करें।\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मानव के रूप में संदेश भेजें (Mind Key नहीं, JWT आवश्यक)।\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# Count unread messages from human (for agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Count unread messages from agent (for human)\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## Polling पैटर्न\n\n> [!TIP]\n> टूल कॉल्स के बीच हर 30-60 सेकंड में poll करें। अधिक बार poll न करें — यह API कोटा बर्बाद करता है और कोई लाभ नहीं देता।\n\n```python\n# Pseudo-code\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- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

Chat API मानव और LLM एजेंट्स के बीच अतुल्यकालिक मैसेजिंग सक्षम करता है। तुल्यकालिक चैट (ChatGPT-शैली) के विपरीत, मानव एजेंट के काम कर रहे होने पर भी संदेश छोड़ सकता है — एजेंट टूल कॉल्स के बीच poll करता है।

\n

यह कैसे काम करता है

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. मानव वेब UI के माध्यम से संदेश भेजता है (JWT का उपयोग करता है)
    2. \n
  2. संदेश स्टोर किया जाता है, अपठित के रूप में चिह्नित किया जाता है
    3. \n
  3. एजेंट टूल कॉल्स के बीच GET /chat/poll कॉल करता है
    4. \n
  4. Poll सभी अपठित संदेश लौटाता है और उन्हें पठित के रूप में चिह्नित करता है
    5. \n
  5. एजेंट संदेश को प्रोसेस करता है, वैकल्पिक रूप से POST /chat/reply के माध्यम से उत्तर देता है
    6. \n
\n

एंडपॉइंट्स

\n

GET /chat/poll

\n

मानव के नए संदेशों के लिए poll करें। अपठित संदेश लौटाता है और उन्हें पठित के रूप में चिह्नित करता है। इसे टूल कॉल्स के बीच उपयोग करें।

\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

मानव के रूप में संदेश भेजें (Mind Key नहीं, JWT आवश्यक)।

\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
# Count unread messages from human (for agent)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Count unread messages from agent (for human)\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

Polling पैटर्न

\n
टूल कॉल्स के बीच हर 30-60 सेकंड में poll करें। अधिक बार poll न करें — यह API कोटा बर्बाद करता है और कोई लाभ नहीं देता।
# Pseudo-code\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"]}