Khách không nhận OTP qua Zalo: 10 nguyên nhân cần kiểm tra

Khách hàng yêu cầu mã OTP nhưng chờ mãi không thấy tin nhắn Zalo. Họ bấm “Gửi lại”, tiếp tục chờ rồi rời khỏi màn hình đăng nhập, thanh toán hoặc xác thực.

Với doanh nghiệp, đây không chỉ là một lỗi gửi tin. Sự cố có thể làm gián đoạn giao dịch, tăng số lượng yêu cầu hỗ trợ và khiến khách hàng mất niềm tin vào dịch vụ.

Điểm quan trọng là doanh nghiệp không nên kết luận “Zalo không gửi OTP” chỉ dựa trên phản ánh của khách hàng. Cần lần theo toàn bộ hành trình của một yêu cầu OTP, từ lúc người dùng bấm gửi mã đến khi hệ thống nhận được trạng thái phân phối cuối cùng.

Trong bài viết này, “OTP qua Zalo” được hiểu là mẫu xác thực thuộc ZBS Template Message, trước đây nhiều doanh nghiệp quen gọi là ZNS OTP.

1. Yêu cầu OTP chưa đi đến bước gọi API

Nguyên nhân đầu tiên cần kiểm tra không nằm ở Zalo mà nằm trong hệ thống của doanh nghiệp.

Khi khách hàng bấm “Gửi mã OTP”, một chuỗi xử lý thường diễn ra:

1. Website, ứng dụng hoặc Mini App ghi nhận yêu cầu.
2. Backend tạo mã OTP.
3. Yêu cầu được đưa vào hàng đợi gửi tin.
4. Dịch vụ gửi tin gọi API Zalo.
5. Hệ thống ghi nhận phản hồi và trạng thái phân phối.

Chỉ cần một bước bị lỗi, mã OTP sẽ không được gửi. Một số tình huống thường gặp gồm:

• Nút gửi mã không kích hoạt đúng sự kiện.
• Backend tạo OTP nhưng không đưa yêu cầu vào hàng đợi.
• Hàng đợi bị nghẽn hoặc dịch vụ gửi tin dừng hoạt động.
• Cơ chế chống gửi liên tục chặn nhầm yêu cầu hợp lệ.
• Hệ thống xảy ra timeout trước khi gọi API.
• Lỗi không được ghi log nên bộ phận kỹ thuật không phát hiện.

Cách kiểm tra

Đội kỹ thuật nên tìm theo một giao dịch cụ thể và xác nhận:

• Thời điểm khách hàng yêu cầu OTP.
• Mã định danh của yêu cầu.
• Số điện thoại đã che bớt thông tin nhạy cảm.
• OTP đã được tạo hay chưa.
• Yêu cầu đã vào hàng đợi hay chưa.
• API Zalo đã được gọi hay chưa.
• Phản hồi API và mã lỗi nhận được.

2. Số điện thoại không đúng hoặc bị sai định dạng

Dữ liệu số điện thoại là một trong những nguyên nhân phổ biến khiến OTP không được gửi.

Theo bảng mã lỗi hiện hành, mã -108 thể hiện số điện thoại không hợp lệ. Tài liệu cũng liệt kê một số định dạng số điện thoại được hỗ trợ khi gửi tin qua số điện thoại. Doanh nghiệp nên đối chiếu trực tiếp với bảng mã lỗi ZBS chính thức tại thời điểm triển khai.

Lỗi dữ liệu thường xuất hiện khi:

• Số điện thoại có khoảng trắng hoặc ký tự đặc biệt.
• Mã quốc gia bị thêm hoặc loại bỏ không đúng.
• File Excel làm mất số 0 ở đầu.
• Khách hàng nhập nhầm số điện thoại.
• Hệ thống lưu một định dạng nhưng dịch vụ gửi tin yêu cầu định dạng khác.
• Doanh nghiệp gửi đến số điện thoại cũ trong hồ sơ khách hàng.

Hướng xử lý

Doanh nghiệp nên chuẩn hóa số điện thoại tại một điểm duy nhất trước khi gửi:

• Loại bỏ khoảng trắng và ký tự không cần thiết.
• Chuyển dữ liệu về kiểu chuỗi để tránh mất số 0.
• Kiểm tra độ dài và đầu số.
• Lưu cả giá trị gốc và giá trị đã chuẩn hóa để đối soát.
• Che bớt số điện thoại trong log và màn hình quản trị.

Không nên để từng website, ứng dụng hoặc hệ thống CRM tự xử lý số điện thoại theo một quy tắc khác nhau.

3. Gửi mẫu OTP qua sai phương thức

Theo tài liệu Zalo, mẫu xác thực OTP hiện không hỗ trợ gửi qua UID. Nếu sử dụng template OTP với phương thức không phù hợp, hệ thống có thể trả mã lỗi -249. Doanh nghiệp cần triển khai OTP theo luồng gửi qua số điện thoại và sử dụng đúng endpoint được cấp phép. Tài liệu mã lỗi ZBS nêu rõ giới hạn này.

Doanh nghiệp có thể tham khảo thêm cách sử dụng mẫu xác thực trong ZBS Template Message trước khi thiết kế luồng gửi.

Cần kiểm tra

• Template đang dùng có đúng là mẫu xác thực không?
• Hệ thống đang gửi qua số điện thoại hay UID?
• Endpoint có đúng với phương thức gửi không?
• Template được tạo trên đúng OA và AppID không?
• Môi trường thử nghiệm và môi trường thật có đang dùng chung cấu hình không?

Đừng chỉ nhìn vào nội dung tin. Template đúng nhưng được gửi qua sai phương thức vẫn có thể khiến toàn bộ luồng OTP thất bại.

4. Template chưa được duyệt hoặc dữ liệu truyền vào không hợp lệ

Mẫu OTP chỉ có thể vận hành ổn định khi trạng thái template và dữ liệu gửi lên đều hợp lệ.

Những lỗi doanh nghiệp cần chú ý gồm:

• Template ID không hợp lệ.
• Template chưa được phê duyệt.
• Thiếu tham số bắt buộc.
• Tên tham số không khớp với template.
• Giá trị tham số vượt giới hạn ký tự.
• Kiểu hoặc định dạng dữ liệu không đúng.
• Nội dung request không đúng cấu trúc JSON.

Trong bảng mã lỗi hiện hành, các tình huống này có thể liên quan đến những mã như -109, -1121, -1122, -1124, -122, -131 hoặc -132. Doanh nghiệp nên đọc mã lỗi thực tế thay vì gửi lại cùng một request nhiều lần.

Trước khi đưa template vào vận hành, đội kỹ thuật nên đối chiếu các định dạng dữ liệu khi truyền tham số ZBS Template.

Checklist kiểm tra template

5. OA, AppID và tài khoản ZBS chưa được liên kết đúng

Một template không tồn tại độc lập. Nó gắn với hệ thống quyền gồm OA, ứng dụng và tài khoản ZBS.

Nếu các thành phần này không khớp, API có thể trả về lỗi dù template đã được duyệt.

Các tình huống thường gặp:

• Template được tạo bằng một OA nhưng hệ thống gửi bằng OA khác.
• AppID chưa được OA ủy quyền.
• Ứng dụng chưa liên kết với tài khoản ZBS.
• Ứng dụng chưa được cấp quyền gửi tin qua số điện thoại.
• Extension chưa có quyền sử dụng tài khoản ZBS của OA.
• Doanh nghiệp thay đổi quản trị viên hoặc cấu hình liên kết nhưng chưa cập nhật hệ thống.

Các mã lỗi có thể gặp gồm -117, -120, -135, -136, -138 và -1381, tùy trường hợp cụ thể.

Doanh nghiệp nên rà lại quy trình liên kết Zalo OA, tài khoản ZBS và ủy quyền cho AppID trước khi can thiệp vào mã nguồn.

6. Access token hoặc thông tin xác thực không hợp lệ

Luồng gửi OTP có thể đang hoạt động bình thường rồi đột ngột lỗi sau khi doanh nghiệp:

• Cập nhật ứng dụng.
• Đổi thông tin quản trị.
• Tạo lại token.
• Thay đổi môi trường triển khai.
• Khôi phục máy chủ từ bản cấu hình cũ.
• Đưa phiên bản mới lên production.

Những thành phần cần kiểm tra gồm:

• Access token.
• AppID.
• App Secret.
• appsecret_proof nếu luồng tích hợp có sử dụng.
• OAID.
• Template ID.
• Quyền của ứng dụng.

Tài liệu Zalo hiện liệt kê các mã như -101, -103, -104, -124, -1241 và -125 cho nhóm lỗi liên quan đến ứng dụng, token và OA.

7. Tài khoản không đủ số dư hoặc đã vượt hạn mức

Một luồng OTP có thể gửi ổn định vào thời điểm lưu lượng thấp nhưng gặp lỗi khi số lượng yêu cầu tăng đột biến.

Doanh nghiệp cần kiểm tra:

• Số dư tài khoản ZBS.
• Trạng thái thanh toán.
• Hạn mức gửi của OA.
• Hạn mức theo template.
• Hạn mức trong môi trường phát triển.
• Khả năng hệ thống đang gửi trùng request làm tiêu hao hạn mức.

Một số mã lỗi liên quan gồm:

• -115: tài khoản không đủ số dư.
• -126: ví ở chế độ phát triển không đủ số dư.
• -137: thanh toán tài khoản ZBS thất bại.
• -144: OA vượt hạn mức gửi qua số điện thoại trong ngày.
• -147: template vượt giới hạn gửi trong ngày.

Doanh nghiệp có thể sử dụng hướng dẫn xử lý mã lỗi ZBS làm tài liệu đối soát ban đầu, sau đó kiểm tra lại mã lỗi trên tài liệu chính thức.

Cách phòng ngừa

• Thiết lập cảnh báo số dư thấp.
• Theo dõi hạn mức còn lại.
• Cảnh báo khi tỷ lệ lỗi tăng bất thường.
• Chặn request trùng.
• Phân biệt lỗi có thể thử lại và lỗi cần sửa cấu hình.
• Không tự động retry vô hạn với mọi mã lỗi.

8. API đã tiếp nhận nhưng doanh nghiệp không theo dõi trạng thái cuối

Một sai lầm phổ biến là coi phản hồi error = 0 là bằng chứng khách hàng đã nhận được OTP.

Phản hồi gửi thành công có thể bao gồm msg_id, sent_time và tracking_id. Trong khi đó, Zalo cung cấp riêng API tra cứu trạng thái gửi và webhook ghi nhận sự kiện người dùng nhận tin qua số điện thoại. Vì vậy, về mặt vận hành, doanh nghiệp nên phân biệt:

• Request chưa được gửi.
• Request bị API từ chối.
• Request được API tiếp nhận.
• Tin đã có trạng thái phân phối.
• Khách hàng nhận được tin nhưng OTP đã hết hiệu lực.

Việc tách các trạng thái này là một suy luận vận hành dựa trên cấu trúc API và webhook trong tài liệu phân quyền ZBS Template Message.

Dữ liệu nên lưu để đối soát

• Mã yêu cầu OTP nội bộ.
• tracking_id.
• msg_id.
• Thời điểm người dùng yêu cầu OTP.
• Thời điểm gọi API.
• Phản hồi API.
• Mã lỗi và nội dung lỗi.
• Trạng thái cuối nhận qua API hoặc webhook.
• Thời điểm OTP hết hiệu lực.
• Số lần gửi lại.

9. Cơ chế gửi lại OTP làm mã đến chậm hoặc bị vô hiệu

Đôi khi khách hàng vẫn nhận được tin Zalo, nhưng mã trong tin không còn sử dụng được.

Đây là lỗi thiết kế luồng xác thực, không đơn thuần là lỗi kênh gửi.

Doanh nghiệp cần thống nhất

• Khi tạo mã mới, mã cũ có bị vô hiệu ngay không?
• Một người dùng được có bao nhiêu mã còn hiệu lực?
• Khoảng chờ giữa hai lần gửi là bao lâu?
• Request trùng được nhận diện bằng cách nào?
• Retry có gửi lại cùng mã hay tạo mã mới?
• Thời gian hiệu lực có phù hợp với độ trễ thực tế không?
• Giao diện có thông báo rõ khi mã mới đã được tạo không?

Mục tiêu không phải gửi thật nhiều OTP mà là giúp khách hàng nhận đúng một mã hợp lệ trong thời gian phù hợp.

10. Người nhận không đủ điều kiện hoặc đã từ chối nhận tin

Sau khi loại trừ nguyên nhân nội bộ, doanh nghiệp mới nên kiểm tra nhóm tình huống từ phía người nhận.

Theo tài liệu Zalo, một số trường hợp có thể gồm:

• Tài khoản Zalo không tồn tại hoặc đã bị vô hiệu hóa: mã -118.
• Người dùng từ chối nhận loại template tương ứng: mã -139.
• Người dùng không đủ điều kiện nhận loại tin theo chính sách hiện tại: mã -140.
• Người dùng đã từ chối nhận tin qua số điện thoại từ OA: mã -141.
• Phiên bản ứng dụng Zalo không được hỗ trợ: mã -110.

Zalo cũng cho biết người dùng có thể chủ động ngừng nhận tin nhắn ZBS từ một OA và doanh nghiệp không thể tự can thiệp để bật lại quyền này. Khi đó, hệ thống cần nhận diện đúng mã lỗi và chuyển sang phương án hỗ trợ phù hợp, thay vì tiếp tục gửi lại vô hạn. Thông tin về quyền ngừng nhận tin ZBS.

Quy trình chẩn đoán khi khách hàng báo không nhận được OTP

Doanh nghiệp có thể sử dụng quy trình sáu bước sau.

Bước 1: Chọn một giao dịch cụ thể

Thu thập thời điểm yêu cầu, số điện thoại đã che bớt, thiết bị, màn hình phát sinh yêu cầu và mã giao dịch nội bộ.

Bước 2: Kiểm tra hệ thống có tạo yêu cầu gửi hay không

Nếu không có request, kiểm tra giao diện, backend, hàng đợi và quy tắc chống gửi liên tục.

Bước 3: Kiểm tra phản hồi API

Không chỉ đọc thông báo “gửi thành công” trên màn hình quản trị. Cần lấy mã lỗi, tracking_id, msg_id, Template ID, OAID và AppID thực tế.

Bước 4: Phân loại lỗi

Bước 5: Thử nghiệm có kiểm soát

Dùng các tài khoản thử nghiệm đã được cho phép, ghi nhận đầy đủ thời gian và không thay đổi nhiều cấu hình cùng lúc. Mỗi lần thử chỉ nên thay đổi một yếu tố để xác định đúng nguyên nhân.

Bước 6: Bổ sung cảnh báo sau khi sửa lỗi

Nếu chỉ sửa trường hợp hiện tại mà không thêm giám sát, sự cố có thể tái diễn mà doanh nghiệp không biết.

Những chỉ số nên theo dõi

Một dashboard OTP qua Zalo nên có tối thiểu:

• Tổng số yêu cầu OTP phát sinh.
• Tỷ lệ request đi đến bước gọi API.
• Tỷ lệ được API tiếp nhận.
• Tỷ lệ có trạng thái phân phối cuối.
• Thời gian từ lúc yêu cầu đến lúc gửi API.
• Thời gian từ lúc gửi đến khi có trạng thái nhận.
• Cơ cấu mã lỗi.
• Tỷ lệ gửi lại OTP.
• Tỷ lệ OTP hết hạn trước khi được sử dụng.
• Tỷ lệ chuyển sang kênh dự phòng.
• Số trường hợp gửi trùng.

Các chỉ số nên được tách theo OA, ứng dụng, template, phiên bản hệ thống và khoảng thời gian. Nhờ đó, doanh nghiệp có thể nhận biết sự cố đang xảy ra cục bộ hay trên toàn bộ luồng gửi.

Có nên chuẩn bị SMS OTP làm kênh dự phòng?

Có thể, nếu giao dịch yêu cầu xác thực liên tục và doanh nghiệp đã đánh giá đầy đủ chi phí, bảo mật cùng trải nghiệm khách hàng.

Doanh nghiệp có thể tham khảo thêm bài so sánh chi phí OTP qua Zalo và SMS OTP để xây dựng phương án đa kênh phù hợp.

Checklist phòng tránh lỗi OTP qua Zalo

Kết luận

Khi khách hàng không nhận được OTP qua Zalo, doanh nghiệp không nên bắt đầu bằng việc gửi lại nhiều lần hoặc mặc định lỗi thuộc về nền tảng.

Cách xử lý đúng là truy vết toàn bộ hành trình: yêu cầu OTP, dữ liệu số điện thoại, template, quyền truy cập, phản hồi API, trạng thái phân phối, thời hạn mã và cơ chế gửi lại.

Một luồng OTP tốt không chỉ cần “gửi được”. Nó phải giúp doanh nghiệp biết chính xác tin đang ở đâu, vì sao thất bại và nên chuyển sang phương án nào mà không làm gián đoạn trải nghiệm khách hàng.