Giới thiệu
Giới thiệu
OMICX AI Assistant là trợ lý AI dạng hội thoại (chatbot) của OMICX. Đối tác bên thứ ba có thể tích hợp trực tiếp qua API để gửi tin nhắn và quản lý cuộc trò chuyện thay mặt người dùng cuối của mình.
Base URL
Tất cả endpoint đều yêu cầu xác thực qua header X-Api-Key — xem chi tiết
tại trang Xác thực.
Ràng buộc theo trợ lý
Scope assistant:execute không phải scope tự chọn — nó chỉ được cấp
cho một API key khi tạo key, và bị ràng buộc với đúng 1 trợ lý. Vì
vậy một key FULL-access thông thường (không được gán riêng) vẫn không
gọi được các endpoint này. Thiếu scope trả về 403 INSUFFICIENT_SCOPE;
key có scope nhưng đã bị gỡ ràng buộc trả về 403 ASSISTANT_NOT_BOUND.
Cuộc trò chuyện (Conversation)
Mỗi cuộc trò chuyện được nhóm theo conversationId. Gửi tin nhắn đầu
tiên không kèm conversationId để bắt đầu cuộc trò chuyện mới — response
trả về conversationId được tạo, dùng cho các tin nhắn tiếp theo trong
cùng cuộc trò chuyện. Mỗi cuộc trò chuyện gắn với một userId do đối tác
tự định danh (người dùng cuối phía đối tác) — dùng để phân tách dữ liệu
giữa các người dùng khác nhau. userId phải là một định danh không
mang nghĩa (không dùng email, số điện thoại, hay tên thật).
Chế độ phản hồi (Response mode)
Hiện tại chỉ hỗ trợ blocking — chờ xử lý xong, trả kết quả trong 1
response (thường vài giây, có thể tới 1 phút). streaming được chấp
nhận trong hợp đồng nhưng hiện tại luôn trả về 501 STREAMING_NOT_AVAILABLE.
Retry & tính phí
Gửi kèm header Idempotency-Key khi gửi tin nhắn để retry an toàn — xem
chi tiết tại API Gửi tin nhắn cho trợ lý. Không
gửi header này, một lần gửi lại sau lỗi mạng sẽ được tính là lượt chat
mới và bị tính phí lần nữa.