Server-to-server

Khi bạn không cần widget — backend của bạn tự gửi message thay mặt end-user của mình, ví dụ để tích hợp vào một hệ thống chat nội bộ, một bot Slack riêng, hay một pipeline xử lý ticket tự động. Không cần đổi token: gọi thẳng POST /v2/chat bằng API key (Console → Khoá API → Tạo khoá — khoá hiện ra đúng một lần lúc tạo).

RequestSao chép liên kết

POST https://api.harnix.vn/v2/chat
Content-Type: application/json
X-API-Key: sk_xxxxxxxxxxxxxxxx
Idempotency-Key: 2f6a...   (khuyến nghị, xem bên dưới)

{
  "agent_id": "b6b0f9b2-...",
  "content": "Chính sách hoàn tiền của chúng tôi là gì?",
  "conversation_id": null,
  "end_user_id": "user_42"
}

• agent_id — bắt buộc, agent phải đang active.
• content — bắt buộc, 1–32000 ký tự.
• conversation_id — bỏ trống để tạo conversation mới; truyền vào để tiếp tục một conversation đã có (phải khớp agent_id, nếu không nhận validation_error).
• end_user_id — có → conversation quy về đúng end-user đó (upsert một end-user identified với external_id là giá trị này); không có → quy về một end-user service đại diện cho chính API key — mọi request không khai end_user_id cùng dùng chung một "người" này.

ResponseSao chép liên kết

202 Accepted — câu trả lời chưa có ngay lúc này, run vẫn đang chạy:

{
  "run_id": "0e2b...",
  "message_id": "9ac1...",
  "conversation_id": "77fd..."
}

Lấy câu trả lời bằng cách stream run này, hoặc đọc lại conversation qua GET /v2/conversations/{id} sau khi run kết thúc.

IdempotencySao chép liên kết

Gửi header Idempotency-Key (tối đa 255 ký tự) để retry an toàn khi mạng timeout giữa chừng — cùng một key trên cùng một conversation + end-user trả về đúng message đã tạo trước đó, không tạo message thứ hai. Chi tiết ở Idempotency & huỷ.

Xác nhận một hành độngSao chép liên kết

Khi agent muốn gọi một tool của connector cần xác nhận, run dừng lại thay vì trả lời: stream của nó phát một frame approval, và GET /v2/conversations/{id} hiện cùng yêu cầu đó trong pending_approval. Backend của bạn quyết định bằng chính API key đó:

POST https://api.harnix.vn/v2/runs/{run_id}/approval
X-API-Key: sk_xxxxxxxxxxxxxxxx
Content-Type: application/json

{ "outcome": "approved" }

outcome là "approved" hoặc "denied"; 202 trả về run, và run chạy tiếp ngay. Qua API key không có remember — gửi kèm sẽ nhận 422 validation_error. Khi một cuộc hội thoại đang có run chờ xác nhận, POST /v2/chat với conversation_id đó trả 409 approval_pending; quyết định trước rồi mới gửi. Toàn bộ quy tắc ở Idempotency & huỷ.

Trả lời câu hỏi (ask_user)Sao chép liên kết

Khi agent gọi tool tích hợp ask_user để hỏi lại người dùng, run dừng lại ở waiting_input thay vì trả lời: stream của nó phát một frame question, và GET /v2/conversations/{id} hiện cùng câu hỏi trong pending_question. Backend của bạn có thể trả lời bằng hai cách:

1. Gọi POST /v2/runs/{run_id}/answer bằng API key:

POST https://api.harnix.vn/v2/runs/{run_id}/answer
X-API-Key: sk_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "answers": [
    { "selected": ["Quận 3"], "other": null }
  ]
}

Trả về 202 Accepted với thông tin run, và run chạy tiếp ngay trên stream.

2. Gửi tin nhắn kế tiếp qua POST /v2/chat:

Khi một cuộc hội thoại đang có run chờ câu hỏi (waiting_input), gọi POST /v2/chat với conversation_id đó sẽ được coi là câu trả lời văn bản tự do của người dùng. Hệ thống trả 202 với chính run đang chờ (không tạo run mới, không bị chặn bởi trần run đồng thời), ghi nhận message vào cuộc hội thoại và tiếp tục xử lý run. Gửi lại với cùng Idempotency-Key trả về cùng run mà không tạo message trùng lặp. Toàn bộ quy tắc ở Idempotency & huỷ.

Giới hạn tần suất & ngân sáchSao chép liên kết

Mỗi API key có trần tần suất riêng (mặc định 300 request/phút, operator chỉnh được) — vượt quá trả rate_limited với retry_after. Một end-user (kể cả end-user service) tối đa 3 run đang chạy cùng lúc — vượt quá trả rate_limited với scope: "active_runs". Nếu tổ chức hoặc agent có ngân sách token theo ngày, hết ngân sách trả budget_exceeded — xem Giới hạn.

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

• Streaming — theo dõi run theo thời gian thực.
• Cuộc hội thoại — liệt kê, đọc lại lịch sử.
• Lỗi — hình lỗi và toàn bộ mã lỗi.
• Lượt chạy & Trace — nội dung chi tiết từng bước của một run cũ bị xoá theo cấu hình lưu trữ của tổ chức bạn; tin nhắn và số liệu sử dụng thì không.