Gửi tin nhắn cho trợ lý
Gửi một tin nhắn tới trợ lý AI mà API key của bạn đang được gán, và nhận câu trả lời ngay trong response này.
Thiếu scope → 403 INSUFFICIENT_SCOPE; key mất ràng buộc → 403 ASSISTANT_NOT_BOUND.
Bạn không được chọn trợ lý nào trả lời. assistantId, tenantId, apiKeyId, model đều được suy ra từ API key; gửi kèm trong body sẽ bị bỏ qua.
Cuộc trò chuyện. Bỏ trống conversationId để mở một cuộc trò chuyện mới; response trả về id để dùng cho các tin nhắn tiếp theo.
Retry và tính phí. Gửi kèm Idempotency-Key — xem mô tả của header này. Nếu không gửi, một lần gửi lại sau lỗi mạng sẽ là lượt chat thứ hai và bị tính phí lần hai.
File đính kèm. Tối đa 5 ảnh mỗi tin nhắn qua files — dùng id từ POST /agent/files/upload (local_file) hoặc một URL https mà OMICX sẽ tự tải (remote_url). File tải lên phải thuộc đúng userId bạn gửi ở đây, nếu không toàn bộ request nhận 404 FILE_NOT_FOUND và không lượt nào bị tính phí. Xem AgentChatFile.
Thời gian xử lý. Một lượt chat thường mất vài giây, có thể lên tới 1 phút — đặt timeout phía client tối thiểu 75 giây. responseMode: streaming dành riêng cho biến thể SSE và hiện tại trả về 501.
Headers
Key tự sinh phía client giúp một lượt chat an toàn khi gửi lại. Rất nên dùng: không có nó, gửi lại sau lỗi mạng là một lượt chat MỚI và bị tính phí lần nữa — server chỉ tự sinh key nội bộ để bảo vệ retry của chính nó, không giúp được phía bạn.
Dùng lại đúng giá trị khi retry. Lượt đã xong được replay lại (replayed: true, không tính phí lại); lượt gốc vẫn đang chạy → 409 (CONVERSATION_BUSY). Ở tin nhắn đầu tiên, id cuộc trò chuyện được suy ra từ chính key này, nên retry sẽ rơi lại đúng cuộc trò chuyện đã mở thay vì tạo thêm cuộc thứ hai.
Một lượt FAILED cũng đã hoàn tất. COMPLETED và FAILED đều là trạng thái cuối, replay không phân biệt — một khi đã FAILED, mọi lần gọi sau cùng key sẽ nhận lại đúng lỗi đó, trợ lý không được hỏi lại. Vì vậy:
- retry vì không thấy phản hồi (timeout, mất kết nối) → cùng key;
- hỏi lại sau khi đã thấy lượt
FAILED→ key MỚI, nếu không sẽ nhận lại đúng lỗi cũ mãi mãi.
Dùng key MỚI cho mỗi tin nhắn mới — dùng lại key cũ sẽ trả về câu trả lời cũ mãi mãi.
Request
Nội dung tin nhắn gửi tới trợ lý.
Không bắt buộc. ID CỦA BẠN cho người dùng cuối của bạn — không phải tài khoản OMICX. Truyền vào để gắn cuộc trò chuyện với đúng người dùng cuối đó, nhờ vậy sau này bạn có thể lọc lại theo userId khi gọi các API tra cứu (tìm cuộc trò chuyện, lấy thông tin cuộc trò chuyện, đổi tên, đánh giá tin nhắn…). Ổn định theo từng người dùng cuối.
Gửi một định danh KHÔNG MANG NGHĨA — tuyệt đối không dùng email, số điện thoại, số CMND/CCCD hay tên thật. OMICX coi giá trị này là một chuỗi vô nghĩa: được lưu nguyên văn, dạng plain text, trên mọi cuộc trò chuyện và mọi lượt chat, và xuất hiện trong báo cáo sử dụng. Không có gì ở đây mã hoá, che dấu hay coi nó là dữ liệu cá nhân — một định danh thật ngoài đời đặt vào field này sẽ trở thành dữ liệu cá nhân dạng plain text trong hệ thống của chúng tôi, do chính bạn đặt vào. Một UUID ngẫu nhiên hoặc key người dùng nội bộ của bạn là đúng hình dạng cần có; nếu cần map lại về một người cụ thể, hãy giữ ánh xạ đó ở phía bạn.
Tiếp tục một cuộc trò chuyện đã có. Bỏ trống để mở cuộc trò chuyện mới — id của cuộc mới được suy ra từ Idempotency-Key, nên gửi lại tin nhắn đầu tiên không tạo thêm cuộc thứ hai. Id để dùng lại được trả về trong response dưới tên conversationId.
blocking (mặc định) — câu trả lời được trả về ngay trong response này. streaming được chấp nhận trong hợp đồng nhưng hiện tại luôn trả 501 STREAMING_NOT_AVAILABLE; sẽ hoạt động mà không cần bạn đổi gì thêm khi ra mắt.
Biến của riêng bạn, được chuyển thẳng cho trợ lý nguyên văn. Không bao giờ được lưu lại hay ghi log.
Giới hạn (vượt quá → 400 AI_ASSISTANT_INPUTS_INVALID): là một object JSON (không phải array), tối đa 50 key ở cấp cao nhất, lồng sâu tối đa 5 cấp, tối đa 16 KiB sau khi serialize.
Ảnh đính kèm cho tin nhắn này, tối đa 5 (nhiều hơn → 400). Hai cách gửi lên — xem AgentChatFile. Bỏ trống nếu không có.
Response
Trợ lý đã trả lời.
Luồng cuộc trò chuyện này thuộc về — gửi lại để tiếp tục.
Tên hiển thị của luồng, tính đến sau lượt chat này.
true khi tin nhắn này mở ra luồng mới.
true khi đây là replay của một lượt chat trước với cùng Idempotency-Key — không tính phí lại.