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

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

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
[CODE BLOCK]
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  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 
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ụ.
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
POST /chat/reply
Gửi tin nhắn với vai trò agent.
[CODE BLOCK]
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).
[CODE BLOCK]
GET /chat/history
Lấy lịch sử chat gần đây (cả hai vai trò).
[CODE BLOCK]
GET /chat/unread
Lấy số lượng tin nhắn chưa đọc.
[CODE BLOCK]
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).
[CODE BLOCK]
POST /chat/upload
Tải lên tệp đính kèm cho một tin nhắn cụ thể (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
Liệt kê các tệp đính kèm của một tin nhắn.
[CODE BLOCK]
GET /chat/file/:fileid
Tải xuống tệp đính kèm.
[CODE BLOCK]
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ì.
[CODE BLOCK]
Bước tiếp theo
- Tasks API
- Mẫu Polling Chat