Khắc phục sự cố Zalo OA¶
Thông tin bài hướng dẫn
Kênh Zalo lỗi thường không báo rõ nguyên nhân — tin nhắn không đến tay khách, mẫu ZBS bị từ chối, hoặc webhook im lặng. Trang này giúp Admin/IT khoanh vùng đúng nhóm lỗi ngay từ đầu, tránh mất thời gian escalate khi bản thân xử lý được.
Phân loại lỗi¶
Nhóm lỗi |
Dấu hiệu |
Nơi kiểm tra |
|---|---|---|
Token / Authorization |
Tài khoản OA ở trạng thái Lỗi, hoặc thẻ tài khoản hiện Token không hợp lệ kèm icon cảnh báo đỏ |
|
Webhook không nhận |
Tin nhắn từ khách không xuất hiện trong Discuss |
Zalo OA Developer Console → Webhook settings |
Gửi tin thất bại |
Trạng thái Zalo = Gửi thất bại trên Zalo trong danh sách Tin nhắn Zalo |
Danh sách Tin nhắn Zalo do Admin cấp quyền truy cập |
Mẫu ZBS bị từ chối / vô hiệu hóa |
Mẫu ở trạng thái Rejected hoặc Disabled |
→ nút Mẫu ZBS |
Không xác định được người nhận |
Lỗi "no valid phone was found"; tin không gửi được |
Form liên lạc trong Viindoo → kiểm tra số điện thoại |
Kiểm tra tin nhắn lỗi¶
Truy cập: Mở danh sách Zalo Events — quyền do Admin cấp (danh sách này không có mục menu mặc định; Admin làm cho nó truy cập được). Sau đó lọc theo khách hàng/OA để kiểm tra.
Hai cột trạng thái trên danh sách:
Trạng thái xử lý — Received / Queued / Processing / Processed / Lỗi (Viindoo không xử lý được)
Trạng thái Zalo — On Queue / Sent / Delivered / Received / Read / Gửi thất bại (Zalo không giao được)
Lọc nhanh: thanh tìm kiếm → filter "Lỗi" (xử lý lỗi) hoặc "Gửi thất bại" (Zalo báo thất bại).
Khôi phục từ form tin nhắn:
Mở tin nhắn lỗi → kiểm tra Trạng thái xử lý và Trạng thái Zalo.
Nếu Trạng thái xử lý = Lỗi → nhấn "Thử lại xử lý" để Viindoo xử lý lại từ đầu.
Nếu Trạng thái Zalo = Gửi thất bại (tin đi chiều gửi) → nhấn "Gửi lại" để gửi lên Zalo lại.
Nếu tin bị kẹt không rõ trạng thái → nhấn "Đánh dấu lỗi" để đánh dấu thủ công rồi retry.
Kiểm tra token và webhook OA¶
Menu:
Mở record tài khoản OA và kiểm tra:
Trường / Chỉ số |
Ý nghĩa |
|---|---|
Statusbar tài khoản |
Dự thảo / Đã kết nối / Lỗi - cần xác thực lại nếu không phải Đã kết nối. Thanh trạng thái còn liệt kê Hết hạn, nhưng Viindoo không tự đặt trạng thái này: lỗi token hiển thị là Lỗi. |
Hạn sử dụng Token |
Trong tab Phê duyệt OAuth, chỉ hiện khi tài khoản ở trạng thái Đã kết nối. Thời điểm token hết hạn; nếu đã qua → re-authorize ngay |
Token hợp lệ |
Trong cùng tab: được tích = Viindoo đang giữ một token chưa đến hạn hết hiệu lực. Thẻ tài khoản trong màn hình Tài khoản hiển thị cùng thông tin đó: Token hợp lệ (dấu tích xanh) hoặc Token không hợp lệ (cảnh báo đỏ); không hợp lệ cũng gồm tài khoản chưa từng được xác thực. |
OAuth Callback URL |
Chỉ đọc — phải khớp chính xác với URL đã đăng ký trong Zalo OA Developer Console |
Webhook URL |
Chỉ đọc — copy và dán vào phần cấu hình Webhook trong Zalo OA Developer Console |
Khôi phục token:
Khi việc xác thực không hoàn tất, hoặc tab Zalo dừng ở một trang trắng chỉ có thông báo ngắn, hoặc tab không mở ra. Hãy tìm điều bạn thấy ở bảng dưới: trường hợp nào cũng xử lý bằng cách nhấn lại "Xác thực tài khoản" - không cần đặt lại tài khoản trước.
Dấu hiệu |
Nguyên nhân |
Cách xử lý |
|---|---|---|
"Lỗi xác thực. Bạn có thể đóng tab này."; trạng thái tài khoản là Lỗi (không đổi nếu lời từ chối đến sau 10 phút) |
Zalo trả về từ chối thay vì cấp quyền, ví dụ do yêu cầu bị từ chối trên trang cấp quyền. Viindoo đặt tài khoản ở trạng thái Lỗi và không lưu token mới. Nếu lời từ chối đến Viindoo sau 10 phút, tab vẫn hiện cùng thông báo nhưng trạng thái không thay đổi. |
Đóng tab, tải lại form tài khoản rồi làm theo các bước bên dưới. |
"Yêu cầu xác thực không hợp lệ hoặc đã hết hạn."; trạng thái tài khoản không thay đổi |
Đã quá 10 phút kể từ lúc Viindoo tạo link (10 phút không tính lại khi bạn nhấn lại "Xác thực tài khoản", vì khi đó link cũ được mở lại), hoặc tab được mở từ một link cũ. |
Làm theo các bước bên dưới. Viindoo tự tạo link mới nên không cần đặt lại. |
"Lỗi xác thực:" kèm một lý do, hoặc "Lỗi xác thực do lỗi không mong muốn."; trạng thái tài khoản là Lỗi |
Viindoo đã nhận được quyền từ Zalo nhưng không đổi được thành token. Lý do ghi sau dấu hai chấm cho biết nguyên nhân. |
Làm theo các bước bên dưới. Nếu lý do cũ xuất hiện lại, kiểm tra App ID, nhập lại App Secret sao chép từ ứng dụng Zalo (trường này chỉ hiện dấu chấm nên không thể đối chiếu bằng mắt) và kiểm tra OAuth Callback URL đăng ký trong Zalo OA Developer Console khớp với URL trên form. |
Không có gì mở ra sau khi nhấn "Xác thực tài khoản"; có cảnh báo "Một cửa sổ tự động đã bị chặn." |
Trình duyệt đã chặn tab mới chứa trang cấp quyền của Zalo. |
Cho phép cửa sổ bật lên (popup) cho địa chỉ Viindoo của bạn rồi nhấn lại "Xác thực tài khoản". |
Mở tài khoản và nhấn "Xác thực tài khoản" để bắt đầu lại OAuth. Viindoo mở trang cấp quyền của Zalo ở tab mới. Link của trang này có hiệu lực 10 phút kể từ lúc link được tạo (nhấn lại trong thời gian đó sẽ mở lại đúng link cũ và không tính lại 10 phút), và nhấn sau thời điểm đó sẽ tự tạo link mới.
Trên trang Zalo, chọn đúng OA bạn đang kết nối (Zalo chọn sẵn OA đầu tiên trong danh sách, có thể không phải OA của bạn) và kiểm tra dòng ngay dưới phần đầu trang ghi đúng OA đó, tích ô đồng ý Điều khoản sử dụng của Zalo rồi nhấn Cấp quyền.
Sau khi authorize xong → nhấn "Đồng bộ thông tin OA" để xác nhận kết nối thành công.
Mẹo
Bạn biết mình làm đúng khi trình duyệt quay về form tài khoản với thanh trạng thái ở Đã kết nối. Sau khi nhấn "Đồng bộ thông tin OA", Tên Zalo OA và ID Zalo OA trong tab Lấy thông tin từ Zalo là của đúng OA bạn định kết nối; nếu không, bạn đã xác thực nhầm OA và lần đồng bộ đã nhập người theo dõi của OA đó thành các liên hệ Zalo (xem cảnh báo bên dưới). Nếu thay vì form là một trang trắng chỉ có thông báo thì việc xác thực chưa hoàn tất: dùng bảng ở trên.
Ghi chú
"Xác thực tài khoản" chỉ hiển thị khi tài khoản chưa có token hợp lệ. Nếu bạn không thấy nút này, Viindoo vẫn đang giữ một token chưa đến hạn hết hiệu lực: nhấn "Đồng bộ thông tin OA" để kiểm tra lại kết nối, và đọc API log nếu vẫn lỗi (xem mục "Xem API log" bên dưới). Nếu bạn đã biết tài khoản đang kết nối nhầm OA, hãy bỏ qua bước đồng bộ và dùng "Xóa phiên OAuth" ở bên dưới.
Cảnh báo
"Xóa phiên OAuth" là thao tác đặt lại có chủ đích, không phải bước sửa lỗi. Không bao giờ dùng nó để xử lý xác thực thất bại hay hết hạn: hãy nhấn lại "Xác thực tài khoản".
Thao tác này xóa phiên OAuth cùng access token và refresh token, đưa tài khoản về Dự thảo (tài khoản có thể chuyển sang Lỗi khi có gì đó gọi lên Zalo). Từ lúc đó Viindoo không gọi được Zalo: mọi lần gửi đều dừng với lỗi "Thiếu token truy cập. Vui lòng phê duyệt tài khoản này.", Viindoo không thể tự làm mới token nữa, và tab Zalo còn mở từ lần nhấn trước sẽ không dùng được nữa. Chỉ khi hoàn tất "Xác thực tài khoản" thì kết nối mới được khôi phục; việc đó cần người quản trị OA trên Zalo nhấn Cấp quyền, và token đã xóa không thể lấy lại.
Chỉ dùng khi bạn muốn chủ động ngắt kết nối OA rồi kết nối lại từ đầu, ví dụ sau khi xác thực nhầm OA. Thao tác này ngắt kết nối tài khoản nhưng không xóa các liên hệ Zalo mà "Đồng bộ thông tin OA" đã nhập từ OA đó. Nếu chưa chắc, hãy nhấn "Xác thực tài khoản" hoặc "Đồng bộ thông tin OA": cả hai đều không xóa token.
Webhook không nhận sự kiện:
Copy giá trị trường Webhook URL → dán vào Zalo OA Developer Console → Webhook settings.
Đảm bảo đã bật đủ nhóm sự kiện: conversation (user_send_*), delivery status, follow/unfollow, ZBS status (change_template_status, change_template_quota, user_feedback).
Kiểm tra mẫu ZBS¶
Truy cập: → chọn tài khoản OA cần kiểm tra → nhấn nút Mẫu ZBS ở đầu form.
Các trạng thái mẫu: Draft → Pending → Approved / Rejected / Disabled
Mẫu bị từ chối (Rejected):
Mở mẫu → đọc trường "Reject reason" — Zalo ghi rõ lý do.
Sửa nội dung mẫu theo yêu cầu.
Nhấn "Đặt về dự thảo" → chỉnh sửa → nhấn "Gửi lên Zalo" để gửi duyệt lại.
Mẫu bị vô hiệu hóa (Disabled):
Trạng thái Disabled = Zalo tắt mẫu do vượt hạn mức hoặc vi phạm chính sách chất lượng.
Trường "Template quality" hiển thị điểm chất lượng Zalo trả về (chỉ đọc).
Ghi chú
Việc theo dõi quota chi tiết và chấm điểm chất lượng ZBS ngay trong Viindoo vẫn đang phát triển. Hiện tại, template bị vô hiệu do vượt quota chỉ hiển thị trạng thái Disabled — kiểm tra giới hạn quota trực tiếp trong Zalo OA Developer Console.
Không xác định được người nhận:
Dấu hiệu |
Nguyên nhân |
Cách xử lý |
|---|---|---|
"no valid phone was found" |
Liên lạc không có số điện thoại hoặc sai định dạng |
Cập nhật số theo định dạng 84xxxxxxxxx trong record liên lạc |
Gửi qua UID không đến |
Đối tác chưa có liên kết Zalo UID trong Viindoo |
Đổi Route policy sang Phone hoặc UID + Phone; kiểm tra liên kết Zalo của đối tác tại Quản lý liên kết đối tác Zalo |
Xem API log¶
API log ghi toàn bộ request Viindoo gửi lên Zalo và response Zalo trả về — nguồn chẩn đoán chính xác nhất khi cần biết mã lỗi cụ thể.
Ba điểm truy cập:
Từ form tài khoản OA → nút "Nhật ký API"
Từ form tin nhắn trong Tin nhắn Zalo → nút "Nhật ký API"
Từ form mẫu ZBS → nút "Nhật ký API"
Đọc log entry:
HTTP status code — 200 = thành công; 401 = token hết hạn; 429 = vượt rate limit
Error message — mô tả lỗi khi request thất bại
Duration — thời gian xử lý (giây); bất thường cao = timeout phía Zalo
Mở form log để xem request body và response data đầy đủ
Checklist trước khi escalate¶
Hoàn thành đủ các bước dưới đây trước khi báo dev hoặc liên hệ Zalo support:
Mở API log của thao tác thất bại → ghi lại HTTP status code và error message.
Kiểm tra trạng thái tài khoản OA và dòng Token hợp lệ / Token không hợp lệ trên thẻ tài khoản → re-authorize nếu token không hợp lệ.
Vào Tin nhắn Zalo → lọc tin nhắn lỗi → ghi lại Trạng thái xử lý và Trạng thái Zalo.
Với mẫu ZBS: đọc trường Reject reason và Template quality.
Kiểm tra Zalo OA Developer Console: hạn mức, URL webhook, trạng thái tài khoản OA.
Tổng hợp để gửi escalate: tên OA, trạng thái tài khoản, timestamp tin lỗi, entry API log, nội dung error message.