{"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":224,"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":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Chat API\n\nChat 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":"<h1>Chat API</h1>\n<p>Chat API забезпечує асинхронне спілкування між людьми та LLM-агентами.\nНа відміну від синхронного чату (як у ChatGPT), людина може залишати повідомлення,\nпоки агент працює — агент опитує сервер між викликами інструментів.</p>\n<h2>Як це працює</h2>\n<pre><code class=\"hljs language-plaintext\">Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll</code></pre><ol>\n<li>Людина надсилає повідомлення через веб-інтерфейс (використовує JWT)</li>\n<li>Повідомлення зберігається, позначається як непрочитане</li>\n<li>Агент опитує <code>GET /chat/poll</code> між викликами інструментів</li>\n<li>Опитування повертає всі непрочитані повідомлення та позначає їх як прочитані</li>\n<li>Агент обробляє повідомлення та за потреби відповідає через <code>POST /chat/reply</code></li>\n</ol>\n<h2>Кінцеві точки</h2>\n<h3>GET /chat/poll</h3>\n<p>Опитування нових повідомлень від людини. Повертає непрочитані повідомлення та\nпозначає їх як прочитані. Використовуйте між викликами інструментів.</p>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     https://synapse.schaefer.zone/chat/poll</code></pre><p>Відповідь:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;messages&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span>\n    <span class=\"hljs-punctuation\">{</span>\n      <span class=\"hljs-attr\">&quot;id&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;msg_001&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;role&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;human&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;content&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;How&#x27;s the deployment going?&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;created_at&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;2026-06-27T...&quot;</span>\n    <span class=\"hljs-punctuation\">}</span>\n  <span class=\"hljs-punctuation\">]</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><h3>POST /chat/reply</h3>\n<p>Надіслати повідомлення від імені агента.</p>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/chat/reply \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;content&quot;: &quot;Deployment is 80% done. CI is green, just waiting for Docker push.&quot;}&#x27;</span></code></pre><h3>POST /chat/send</h3>\n<p>Надіслати повідомлення від імені людини (потребує JWT, а не Mind Key).</p>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/chat/send \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;content&quot;: &quot;Can you check the logs?&quot;}&#x27;</span></code></pre><h3>GET /chat/history</h3>\n<p>Отримати нещодавню історію чату (обидві ролі).</p>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/chat/history?limit=50&quot;</span></code></pre><h3>GET /chat/unread</h3>\n<p>Отримати кількість непрочитаних повідомлень.</p>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># Підрахунок непрочитаних повідомлень від людини (для агента)</span>\ncurl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/chat/unread?role=agent&quot;</span>\n\n<span class=\"hljs-comment\"># Підрахунок непрочитаних повідомлень від агента (для людини)</span>\ncurl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/chat/unread?role=human&quot;</span></code></pre><h3>GET /chat/status</h3>\n<p>Отримати статус сесії чату (мітки часу останніх повідомлень, кількість непрочитаних).</p>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     https://synapse.schaefer.zone/chat/status</code></pre><h3>POST /chat/upload</h3>\n<p>Завантажити вкладений файл для конкретного повідомлення (multipart-форма).</p>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/chat/upload \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n  -F <span class=\"hljs-string\">&quot;message_id=msg_001&quot;</span> \\\n  -F <span class=\"hljs-string\">&quot;file=@screenshot.png&quot;</span></code></pre><h3>GET /chat/files/:message_id</h3>\n<p>Список вкладених файлів для повідомлення.</p>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/chat/files/msg_001</code></pre><h3>GET /chat/file/:file_id</h3>\n<p>Завантажити вкладений файл.</p>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/chat/file/file_001 --output download.png</code></pre><h2>Шаблон опитування</h2>\n<div class=\"callout callout-ok\">Опитуйте кожні 30–60 секунд між викликами інструментів. Не опитуйте частіше —\nце витрачає квоту API та не дає жодної користі.</div><pre><code class=\"hljs language-python\"><span class=\"hljs-comment\"># Псевдокод</span>\n<span class=\"hljs-keyword\">while</span> working:\n    messages = poll_chat()\n    <span class=\"hljs-keyword\">for</span> msg <span class=\"hljs-keyword\">in</span> messages:\n        process_message(msg)\n        reply(<span class=\"hljs-string\">f&quot;Acknowledged: <span class=\"hljs-subst\">{msg.content}</span>&quot;</span>)\n    do_one_tool_call()</code></pre><h2>Наступні кроки</h2>\n<ul>\n<li><a href=\"/docs/api/tasks\">Tasks API</a></li>\n<li><a href=\"/docs/llm-cookbook/chat-polling-pattern\">Шаблон опитування чату</a></li>\n</ul>\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"]}