Khắc phục sự cố Zalo OA

Thông tin bài hướng dẫn

Đối tượng: Admin/IT, Ops

Thời gian: 5-15 phút tuỳ nhóm lỗi.

Kết quả đạt được: Xác định đúng nhóm lỗi Zalo (token, webhook, gửi tin, mẫu ZBS) và khôi phục kênh mà không cần escalate dev

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 Expired hoặc Error; icon cảnh báo đỏ	Zalo ‣ Cấu hình ‣ Tài khoản
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	Zalo ‣ Cấu hình ‣ Tài khoản → 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:

1. Mở tin nhắn lỗi → kiểm tra Trạng thái xử lý và Trạng thái Zalo.

2. Nếu Trạng thái xử lý = Lỗi → nhấn "Thử lại xử lý" để Viindoo xử lý lại từ đầu.

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

4. 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: Zalo ‣ Cấu hình ‣ Tài khoản

Mở record tài khoản OA và kiểm tra:

Trường / Chỉ số	Ý nghĩa
Statusbar tài khoản	Draft / Connected / Expired / Error — cần re-authorize nếu không phải Connected
Token expires at	Thời điểm token hết hạn; nếu đã qua → re-authorize ngay
Icon trạng thái token	Dấu tích xanh = hợp lệ; cảnh báo đỏ = hết hạn hoặc lỗi
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:

1. Tài khoản ở trạng thái Expired hoặc Error → nhấn "Xác thực tài khoản" để bắt đầu lại OAuth.

2. Nếu nút "Xác thực tài khoản" bị kẹt hoặc hiển thị session cũ → nhấn "Xóa phiên OAuth" trước.

Cảnh báo

"Xóa phiên OAuth" xóa phiên OAuth đang dở. Chỉ dùng khi luồng authorize bị treo — không nhấn tùy tiện.

3. Sau khi authorize xong → nhấn "Đồng bộ thông tin OA" để xác nhận kết nối thành công.

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: Zalo ‣ Cấu hình ‣ Tài khoản → 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):

1. Mở mẫu → đọc trường "Reject reason" — Zalo ghi rõ lý do.

2. Sửa nội dung mẫu theo yêu cầu.

3. 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:

1. Mở API log của thao tác thất bại → ghi lại HTTP status code và error message.

2. Kiểm tra trạng thái tài khoản OA và icon token → re-authorize nếu hết hạn.

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

4. Với mẫu ZBS: đọc trường Reject reason và Template quality.

5. Kiểm tra Zalo OA Developer Console: hạn mức, URL webhook, trạng thái tài khoản OA.

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

Tài liệu liên quan

• Cấu hình và kết nối OA lần đầu → Cấu hình Zalo OA

• Tạo, duyệt và gửi mẫu ZBS → Đăng ký và quản lý Mẫu tin ZBS (Admin/IT)