Gọi trợ lý — /agent/process
Điểm vào duy nhất xử lý một lượt hội thoại bằng chữ, giọng nói hoặc thao tác giao diện.
POST https://api.aivigo.tech/api/v1/agent/process
Authorization: Bearer ak_…
Content-Type: application/json
Idempotency-Key: 6f1c… (tuỳ chọn)Request
| Trường | Kiểu | Mô tả |
|---|---|---|
input | object, bắt buộc | Nội dung lượt — xem bên dưới |
session_id | uuid | Bỏ trống để mở phiên mới; gửi lại để tiếp tục hội thoại |
user | object | Người dùng cuối: ref (mã trong hệ thống của bạn), name, phone, email, org_ref, roles, country, attributes |
app | string | App ID — chỉ cần khi API key không gắn App |
channel | string | Kênh: api (mặc định), app, web… |
screen_context | object | Ngữ cảnh màn hình (khách đang xem gì, ở cửa hàng nào) — xem Tham số trang |
output | object | { "text": true, "ui": true, "audio": false, "voice": "…" } — bật/tắt kênh trả về |
locale | string | Mặc định vi-VN |
context | object | Dữ liệu truyền cho công cụ nghiệp vụ (vd. store_id) |
Ba loại input
{ "input": { "type": "text", "text": "tôi muốn đặt 2 hộp sữa tươi" }, "user": { "ref": "kh001", "name": "An" } }Mặc định tối đa 2.000 ký tự (vượt ⇒ 422 input_too_long).
Response
{
"turn_id": "0199a…",
"session_id": "0199b…",
"status": "awaiting_confirm",
"agent": "sales",
"reply": {
"text": "Mình xác nhận đơn hàng 2 hộp sữa tươi, tổng 64.000đ nhé?",
"ui": [
{ "type": "order_summary", "items": [{ "name": "Sữa tươi 1L", "qty": 2, "price": 32000 }], "total": 64000 },
{ "type": "actions", "buttons": [
{ "label": "Đồng ý", "action": "confirm", "style": "primary" },
{ "label": "Huỷ", "action": "deny" }
] }
]
},
"intent": { "key": "sales.order_create", "tier": "L1", "confidence": 0.94 },
"data": {},
"degraded": false,
"latency_ms": 820
}| Trường | Ý nghĩa |
|---|---|
status | completed — xong · awaiting_input — trợ lý đang hỏi thêm · awaiting_confirm — chờ người dùng bấm xác nhận · handoff — cần chuyển nhân viên · cancelled · failed |
reply.text | Câu trả lời để hiển thị / đọc |
reply.ui | Danh sách khối giao diện |
reply.audio | { format, base64, duration_ms } khi bật âm thanh |
agent | Trợ lý chuyên môn đã xử lý (bán hàng, CSKH…) |
data | Dữ liệu có cấu trúc của lượt (vd. order_id, total) để cập nhật giao diện của bạn |
degraded | true = hệ thống đã dùng đường dự phòng (AI chậm/lỗi) — vẫn hiển thị câu trả lời bình thường |
Xử lý status handoff
Khi status = "handoff", hãy mở kênh hỗ trợ của bạn (chat nhân viên, hotline) — trợ lý đã báo người dùng rằng sẽ có người hỗ trợ.
Gửi lại an toàn — Idempotency-Key
Mạng chập chờn khiến bạn không biết lượt đã được xử lý chưa (đặc biệt khi tạo đơn). Gửi header
Idempotency-Key (vd. UUID) cho mỗi lượt:
- Gửi lại cùng khoá + cùng body sau khi lượt xong ⇒ nhận lại đúng kết quả cũ (header
Idempotent-Replayed: true), không tạo đơn mới. - Lượt đang xử lý ⇒
409. Cùng khoá nhưng khác body ⇒422. - Khoá được giữ 24 giờ. Lượt lỗi không được lưu nên có thể gửi lại.
Ví dụ theo ngôn ngữ
const res = await fetch('https://api.aivigo.tech/api/v1/agent/process', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.AIVIGO_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({ session_id, input: { type: 'text', text }, user: { ref: user.id, name: user.name } }),
});
if (!res.ok) throw new Error((await res.json()).code);
const turn = await res.json();