Chat API

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

Cách hoạt động

Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── marks messages as read on poll

1. Con người gửi tin nhắn qua giao diện web (sử dụng JWT)
2. Tin nhắn được lưu, đánh dấu là chưa đọc
3. Agent poll GET /chat/poll giữa các lần gọi công cụ
4. Poll trả về tất cả tin nhắn chưa đọc và đánh dấu là đã đọc
5. Agent xử lý tin nhắn, có thể trả lời qua POST /chat/reply

Các endpoint

GET /chat/poll

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à đã đọc. Sử dụng giữa các lần gọi công cụ.

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

Phản hồi:

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

POST /chat/reply

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

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

POST /chat/send

Gửi tin nhắn với vai trò con người (yêu cầu JWT, không phải Mind Key).

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

GET /chat/history

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

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

GET /chat/unread

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

# Count unread messages from human (for agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Count unread messages from agent (for human)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

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

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

POST /chat/upload

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

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

GET /chat/files/:message_id

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

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

GET /chat/file/:file_id

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

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

Mẫu poll

# Pseudo-code
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()

Bước tiếp theo

• Tasks API
• Mẫu Polling Chat