Xử Lý Sự Cố & Câu Hỏi Thường Gặp (FAQ)
Tổng hợp các lỗi thường gặp trong quá trình tích hợp Chatbot Service và cách xử lý nhanh chóng.
1. Bảng Mã Lỗi Thường Gặp
| Mã Lỗi | Nguyên Nhân Phổ Biến | Cách Khắc Phục |
|---|---|---|
401 Unauthorized | JWT Token hết hạn hoặc chưa đăng nhập ExternalLogin. | Kiểm tra interceptor, kích hoạt cơ chế Auto-Recovery Token 401. |
403 Forbidden | Thiếu hoặc sai x-external-private-key hoặc orgId. | Kiểm tra file .env, đối chiếu lại Private Key do Pango cấp. |
Invalid Checksum | Công thức tính MD5 Checksum không đúng thứ tự hoặc lệch đồng hồ quá 5 phút. | Kiểm tra công thức platformCode:requestTime:platformUserId và đồng bộ giờ hệ thống qua NTP. |
BAD_USER_INPUT | Sai định dạng biến variables hoặc thiếu trường bắt buộc. | Đối chiếu lại GraphQL schema và kiểu dữ liệu trong tài liệu từng API. |
Firestore: Permission Denied | Firestore Rules không cho phép đọc path hoặc cấu hình projectId sai. | Kiểm tra lại các biến VITE_FIREBASE_* trong file .env. |
2. Câu Hỏi Thường Gặp (FAQ)
Q1: Tại sao gọi SendAiMessage thành công nhưng màn hình không hiển thị câu trả lời?
Trả lời:
SendAiMessagechỉ khởi tạo phiên và gửi tin nhắn vào hàng đợi xử lý của mô hình AI. Để hiển thị câu trả lời, bạn bắt buộc phải lắng nghe Firestore realtime theo đường dẫn document chứaassistantMessageIdtrả về. Xem hướng dẫn tại Firebase Realtime Stream.
Q2: Người dùng gửi ảnh thì truyền như thế nào?
Trả lời: Mutation
SendAiMessagehỗ trợ tham số$images: [Upload!]. Bạn có thể gửi Multipart form-data chứa file ảnh, hoặc truyền URL ảnh đã upload vào trườngimageUrlstrongAiChatRequestDtoInput.
Q3: Có cần gọi ExternalLogin mỗi lần mở màn hình chat không?
Trả lời: Không cần thiết. Bạn chỉ cần lưu
accessTokenvào Secure Storage và tái sử dụng cho đến khi nhận lỗi401 Unauthorized. Khi đó mới gọi lạiExternalLoginđể lấy token mới.
Q4: Ứng dụng có thể tùy biến giao diện bong bóng chat không?
Trả lời: Hoàn toàn có thể. Vì Pango cung cấp dữ liệu qua API GraphQL và Firebase Firestore thuần túy (Headless API), đội ngũ phát triển Mobile App và Web App có toàn quyền thiết kế giao diện, màu sắc, font chữ và hiệu ứng tương thích 100% với Design System của doanh nghiệp bạn.