AI AssistantTrò chuyện

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

X-Api-KeystringRequired
Idempotency-KeystringOptional<=100 characters
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

This endpoint expects an object.
messagestringRequired<=16000 characters

Nội dung tin nhắn gửi tới trợ lý.

userIdstringOptional<=100 characters

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.

conversationIdstringOptional

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.

responseModeenumOptionalDefaults to blocking

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.

inputsmap from strings to anyOptional

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.

fileslist of objectsOptional

Ả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.

conversationIdstringOptional

Luồng cuộc trò chuyện này thuộc về — gửi lại để tiếp tục.

titlestringOptional

Tên hiển thị của luồng, tính đến sau lượt chat này.

newConversationbooleanOptional

true khi tin nhắn này mở ra luồng mới.

replayedbooleanOptional

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.

turnobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
501
Not Implemented Error
502
Bad Gateway Error
503
Service Unavailable Error