Cuộc hội thoại

Các endpoint dưới đây dùng khi bạn tự xây giao diện chat của riêng mình thay vì dùng widget <harnix-chat> — chúng đều xác thực bằng token của end-user (Authorization: Bearer <token>, xem Xác thực), không phải API key.

Danh sách agent khả dụngSao chép liên kết

GET https://api.harnix.vn/v2/agents
Authorization: Bearer <token>

[{ "id": "b6b0f9b2-...", "name": "Trợ lý hỗ trợ" }]

Trả về mọi agent đang active của tổ chức — token không gắn với một agent cụ thể nào.

Tạo cuộc hội thoại mớiSao chép liên kết

POST https://api.harnix.vn/v2/conversations
Authorization: Bearer <token>
Content-Type: application/json

{ "agent_id": "b6b0f9b2-..." }

Trả về 201 với ConversationRead: { id, agent_id, title, created_at, last_message_at }. title là null cho tới khi có một giá trị được đặt sau này (console cho phép đặt tên).

Liệt kê cuộc hội thoạiSao chép liên kết

GET https://api.harnix.vn/v2/conversations?agent_id=...&limit=20&before=...
Authorization: Bearer <token>

Chỉ trả về cuộc hội thoại của chính end-user đang gọi — không có cách nào để một end-user đọc conversation của người khác, kể cả biết ID. Phân trang kiểu keyset: dùng next_before của trang trước làm before của trang sau; limit tối đa 50 (mặc định 50).

{
  "items": [{ "id": "77fd...", "agent_id": "b6b0f9b2-...", "title": null, "created_at": "...", "last_message_at": "..." }],
  "next_before": "77fd..."
}

Đọc một cuộc hội thoạiSao chép liên kết

GET https://api.harnix.vn/v2/conversations/{conversation_id}?before_seq=...
Authorization: Bearer <token>

Trả về ConversationDetail — thông tin cuộc hội thoại kèm tối đa 50 message gần nhất (messages). Mỗi message có role (user hoặc assistant), content, citations (chỉ có ở message của assistant, hoặc null), seq (thứ tự tăng dần trong conversation), và run_id (run đã sinh ra message này, dùng để stream hoặc xem lại). Dùng before_seq để lấy trang cũ hơn.

pending_approval cho biết cuộc hội thoại có đang dừng chờ người dùng xác nhận một hành động hay không: null khi không có, hoặc { run_id, expires_at, calls: [{ call_id, server_name, name, title, arguments }] } — cùng nội dung với khung approval của stream. Dùng nó khi người dùng mở lại trang: dựng lại lời hỏi xác nhận từ đây và trả lời bằng POST /v2/runs/{run_id}/approval, không cần mở lại stream.

pending_question cho biết cuộc hội thoại có đang dừng chờ người dùng trả lời câu hỏi (ask_user) hay không: null khi không có, hoặc { run_id, call_id, expires_at, questions: [...] } — cùng nội dung với khung question của stream. Dùng nó khi người dùng mở lại trang: dựng lại giao diện câu hỏi từ đây và trả lời bằng POST /v2/runs/{run_id}/answer hoặc gửi tin nhắn tiếp theo mà không cần mở lại stream.

Một conversation không thuộc về bạn, hoặc không tồn tại — cùng một conversation_not_found (404): endpoint không xác nhận sự tồn tại của conversation người khác.

Gửi message trong một cuộc hội thoạiSao chép liên kết

POST https://api.harnix.vn/v2/conversations/{conversation_id}/messages
Authorization: Bearer <token>
Idempotency-Key: 2f6a...   (khuyến nghị)
Content-Type: application/json

{ "content": "Chính sách hoàn tiền của chúng tôi là gì?" }

202 Accepted với { run_id, message_id, conversation_id } — giống hệt POST /v2/chat, khác ở chỗ conversation đã xác định sẵn qua URL và người gửi là end-user đang cầm token, không phải một API key.

Trong lúc cuộc hội thoại có một hành động chờ xác nhận (pending_approval khác null), gửi message mới trả 409 approval_pending — xác nhận hoặc từ chối hành động đó trước. Gửi lại đúng message đã tạo ra run đang chờ, với cùng Idempotency-Key, vẫn trả 202 với run đó như bình thường.

Ngược lại, khi cuộc hội thoại đang có câu hỏi chờ trả lời (pending_question khác null), gửi message mới không bị lỗi: tin nhắn mới được xem là câu trả lời văn bản tự do của người dùng cho câu hỏi đó. Endpoint trả 202 với chính run đang chờ (không tạo run mới, không tính vào trần 3 run đồng thời), ghi nhận message vào lịch sử và tiếp tục lượt chạy. Gửi lại cùng Idempotency-Key trả về cùng run mà không tạo message trùng lặp.

Bước tiếp theoSao chép liên kết

• Streaming — theo dõi run_id vừa nhận theo thời gian thực.
• Idempotency & huỷ — kể cả cách xác nhận hành động hay trả lời câu hỏi đang chờ.
• Lượt chạy & Trace — lịch sử hội thoại qua API này không bị xoá theo cấu hình lưu trữ trace của tổ chức bạn.