{"title":"Chat API","slug":"chat","category":"api","summary":"Trò chuyện bất đồng bộ giữa con người và LLM agent — poll, reply, history, đếm chưa đọc, tải tệp lên.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":312,"read_minutes":2,"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":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Chat API\n\nChat API cho phép nhắn tin bất đồng bộ giữa con người và các LLM agent. Khác\nvới chat đồng bộ (kiểu ChatGPT), con người có thể để lại tin nhắn trong khi\nagent đang làm việc — agent sẽ poll giữa các lần gọi công cụ.\n\n## Cách hoạt động\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Con người gửi tin nhắn qua giao diện web (sử dụng JWT)\n2. Tin nhắn được lưu, đánh dấu là chưa đọc\n3. Agent poll `GET /chat/poll` giữa các lần gọi công cụ\n4. Poll trả về tất cả tin nhắn chưa đọc và đánh dấu là đã đọc\n5. Agent xử lý tin nhắn, có thể trả lời qua `POST /chat/reply`\n\n## Các endpoint\n\n### GET /chat/poll\n\nPoll tin nhắn mới từ con người. Trả về các tin nhắn chưa đọc và đánh dấu là đã\nđọc. Sử dụng giữa các lần gọi công cụ.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nPhản hồi:\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\nGửi tin nhắn với vai trò agent.\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\nGửi tin nhắn với vai trò con người (yêu cầu JWT, không phải 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\nLấy lịch sử chat gần đây (cả hai vai trò).\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\nLấy số lượng tin nhắn chưa đọc.\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\nLấy trạng thái phiên chat (thời gian tin nhắn cuối, số lượng chưa đọc).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nTải lên tệp đính kèm cho một tin nhắn cụ thể (multipart form).\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\nLiệt kê các tệp đính kèm của một tin nhắ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\nTải xuống tệp đính kèm.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## Mẫu poll\n\n> [!TIP]\n> Poll mỗi 30-60 giây giữa các lần gọi công cụ. Đừng poll thường hơn —\n> điều này làm lãng phí hạn ngạch API và không mang lại lợi ích gì.\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## Bước tiếp theo\n\n- [Tasks API](/docs/api/tasks)\n- [Mẫu Polling Chat](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

Chat API cho phép nhắn tin bất đồng bộ giữa con người và các LLM agent. Khác\nvới chat đồng bộ (kiểu ChatGPT), con người có thể để lại tin nhắn trong khi\nagent đang làm việc — agent sẽ poll giữa các lần gọi công cụ.

\n

Cách hoạt động

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Con người gửi tin nhắn qua giao diện web (sử dụng JWT)
    2. \n
  2. Tin nhắn được lưu, đánh dấu là chưa đọc
    3. \n
  3. Agent poll GET /chat/poll giữa các lần gọi công cụ
    4. \n
  4. Poll trả về tất cả tin nhắn chưa đọc và đánh dấu là đã đọc
    5. \n
  5. Agent xử lý tin nhắn, có thể trả lời qua POST /chat/reply
    6. \n
\n

Các endpoint

\n

GET /chat/poll

\n

Poll tin nhắn mới từ con người. Trả về các tin nhắn chưa đọc và đánh dấu là đã\nđọc. Sử dụng giữa các lần gọi công cụ.

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

Phản hồi:

\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

Gửi tin nhắn với vai trò agent.

\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

Gửi tin nhắn với vai trò con người (yêu cầu JWT, không phải 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

Lấy lịch sử chat gần đây (cả hai vai trò).

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

GET /chat/unread

\n

Lấy số lượng tin nhắn chưa đọc.

\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

Lấy trạng thái phiên chat (thời gian tin nhắn cuối, số lượng chưa đọc).

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

POST /chat/upload

\n

Tải lên tệp đính kèm cho một tin nhắn cụ thể (multipart form).

\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

Liệt kê các tệp đính kèm của một tin nhắn.

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

GET /chat/file/:file_id

\n

Tải xuống tệp đính kèm.

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

Mẫu poll

\n
Poll mỗi 30-60 giây giữa các lần gọi công cụ. Đừng poll thường hơn —\nđiều này làm lãng phí hạn ngạch API và không mang lại lợi ích gì.
# 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()

Bước tiếp theo

\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"]}