{"title":"Chat API","slug":"chat","category":"api","summary":"Chat asinkron antara manusia dan agen LLM — polling, balas, riwayat, jumlah belum dibaca, unggah file.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":234,"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":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Chat API\n\nChat API memungkinkan pesan asinkron antara manusia dan agen LLM.\nBerbeda dengan chat sinkron (gaya ChatGPT), manusia dapat meninggalkan pesan\nsaat agen sedang bekerja — agen melakukan polling di antara pemanggilan alat.\n\n## Cara Kerja\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Manusia mengirim pesan melalui web UI (menggunakan JWT)\n2. Pesan disimpan, ditandai sebagai belum dibaca\n3. Agen melakukan polling `GET /chat/poll` di antara pemanggilan alat\n4. Polling mengembalikan semua pesan belum dibaca dan menandainya sebagai sudah dibaca\n5. Agen memproses pesan, secara opsional membalas melalui `POST /chat/reply`\n\n## Endpoint\n\n### GET /chat/poll\n\nPolling pesan baru dari manusia. Mengembalikan pesan belum dibaca dan\nmenandainya sebagai sudah dibaca. Gunakan ini di antara pemanggilan alat.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nRespons:\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\nMengirim pesan sebagai agen.\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\nMengirim pesan sebagai manusia (memerlukan JWT, bukan 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\nMengambil riwayat chat terbaru (kedua peran).\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\nMengambil jumlah pesan belum dibaca.\n\n```bash\n# Menghitung pesan belum dibaca dari manusia (untuk agen)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Menghitung pesan belum dibaca dari agen (untuk manusia)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### GET /chat/status\n\nMengambil status sesi chat (timestamp pesan terakhir, jumlah belum dibaca).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nMengunggah lampiran file untuk pesan tertentu (form 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\nMendaftar lampiran file untuk sebuah pesan.\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\nMengunduh lampiran file.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## Pola Polling\n\n> [!TIP]\n> Lakukan polling setiap 30-60 detik di antara pemanggilan alat. Jangan polling\n> lebih sering dari itu — ini membuang kuota API dan tidak memberikan manfaat.\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## Langkah Berikutnya\n\n- [Tasks API](/docs/api/tasks)\n- [Pola Polling Chat](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

Chat API memungkinkan pesan asinkron antara manusia dan agen LLM.\nBerbeda dengan chat sinkron (gaya ChatGPT), manusia dapat meninggalkan pesan\nsaat agen sedang bekerja — agen melakukan polling di antara pemanggilan alat.

\n

Cara Kerja

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Manusia mengirim pesan melalui web UI (menggunakan JWT)
    2. \n
  2. Pesan disimpan, ditandai sebagai belum dibaca
    3. \n
  3. Agen melakukan polling GET /chat/poll di antara pemanggilan alat
    4. \n
  4. Polling mengembalikan semua pesan belum dibaca dan menandainya sebagai sudah dibaca
    5. \n
  5. Agen memproses pesan, secara opsional membalas melalui POST /chat/reply
    6. \n
\n

Endpoint

\n

GET /chat/poll

\n

Polling pesan baru dari manusia. Mengembalikan pesan belum dibaca dan\nmenandainya sebagai sudah dibaca. Gunakan ini di antara pemanggilan alat.

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

Respons:

\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

Mengirim pesan sebagai agen.

\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

Mengirim pesan sebagai manusia (memerlukan JWT, bukan 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

Mengambil riwayat chat terbaru (kedua peran).

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

GET /chat/unread

\n

Mengambil jumlah pesan belum dibaca.

\n
# Menghitung pesan belum dibaca dari manusia (untuk agen)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Menghitung pesan belum dibaca dari agen (untuk manusia)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

\n

Mengambil status sesi chat (timestamp pesan terakhir, jumlah belum dibaca).

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

POST /chat/upload

\n

Mengunggah lampiran file untuk pesan tertentu (form 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

Mendaftar lampiran file untuk sebuah pesan.

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

GET /chat/file/:file_id

\n

Mengunduh lampiran file.

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

Pola Polling

\n
Lakukan polling setiap 30-60 detik di antara pemanggilan alat. Jangan polling\nlebih sering dari itu — ini membuang kuota API dan tidak memberikan manfaat.
# 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()

Langkah Berikutnya

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