# 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ụ.

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

Phản hồi:

```json
{
  "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.

```bash
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).

```bash
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ò).

```bash
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.

```bash
# 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).

```bash
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).

```bash
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.

```bash
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.

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

## Mẫu poll

> [!TIP]
> Poll mỗi 30-60 giây giữa các lần gọi công cụ. Đừng poll thường hơ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ì.

```python
# 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](/docs/api/tasks)
- [Mẫu Polling Chat](/docs/llm-cookbook/chat-polling-pattern)