Vì sao template cũ không gửi được qua UID (lỗi -249)?

Lỗi -249 (Template does not support send via UID) xảy ra với các template tạo trước ngày 10/12/2025 (template ZNS cũ), template OTP, template chứa component Response hoặc template Journey. Để gửi qua UID, bạn cần tạo mới hoặc clone lại template theo chuẩn ZBS Template Message (template tùy chỉnh, đánh giá dịch vụ, yêu cầu thanh toán hoặc voucher).

Lỗi -131 'Template not approved' xử lý thế nào?

Lỗi -131 nghĩa là template chưa được Zalo phê duyệt. Template ZBS cần được duyệt (thường 2-3 ngày làm việc) trước khi dùng để gửi. Chỉ chọn template có trạng thái ENABLE/đã duyệt khi cấu hình chiến dịch gửi tin.

Làm sao tránh gửi trùng tin ZBS và bị tính phí nhiều lần?

Dùng khóa idempotency theo bộ (sự kiện nghiệp vụ + mã đơn) để mỗi sự kiện chỉ gửi một lần, và chỉ kích hoạt gửi khi trạng thái đơn thực sự thay đổi. Vì tracking_id thường gắn timestamp nên Zalo không tự khử trùng — việc chống trùng phải do hệ thống của bạn đảm nhiệm.

Lỗi gửi tin ZBS Template Message: Bảng mã lỗi & cách xử lý thực tế (2026)

Q: Lỗi -137 khi gửi tin ZBS nghĩa là gì?

Lỗi -137 (ZBS Account charge failure) nghĩa là không trừ được tiền từ tài khoản ZBS — thường do tài khoản ZBS dùng để tính phí không đủ số dư. Cần kiểm tra và nạp tiền vào ZBS Account. Lỗi này khác với ví nội bộ của từng cửa hàng: ZBS Account là nơi giữ tiền thật để Zalo trừ phí mỗi tin gửi qua số điện thoại.

Q: Lỗi -115 và -137 khác nhau thế nào?

Cả hai đều liên quan đến số dư tài khoản ZBS. -115 (Out of quota) báo tài khoản ZBS không đủ số dư trước khi gửi; -137 (ZBS Account charge failure) báo bước trừ tiền thất bại khi đang gửi. Hướng xử lý giống nhau: truy cập ZBS Account để kiểm tra số dư và nạp thêm.

Tóm tắt nhanh: Phần lớn lỗi gửi tin ZBS Template Message rơi vào 4 nhóm — ví/tính phí (-115, -137), quyền & template (-117, -120, -131, -135), dữ liệu (-108, -118, -1122, -1124) và gửi qua UID (-249). Bài viết tổng hợp ý nghĩa từng mã và cách xử lý từ kinh nghiệm tích hợp thực tế của Zimo.

ZBS Template Message là giải pháp gửi tin nhắn doanh nghiệp theo mẫu của Zalo (ra mắt đầu 2026), hợp nhất ZNS và các loại tin UID cũ. Khi tích hợp API gửi tin, đội kỹ thuật thường gặp một số mã lỗi lặp đi lặp lại. Dưới đây là cách chúng tôi phân loại và xử lý chúng trong thực tế.

Vì sao tin ZBS gửi thất bại?

API gửi tin qua số điện thoại trả về trường error: 0 là thành công, số âm là lỗi. Mỗi mã lỗi chỉ ra một nguyên nhân cụ thể — hiểu đúng nhóm lỗi giúp bạn xử lý trong vài phút thay vì dò mò.

Nhóm 1 — Lỗi ví & tính phí (tài khoản ZBS dùng chung)

Tin ZBS qua số điện thoại bị Zalo trừ phí trực tiếp từ ZBS Account. Đây là nhóm lỗi tốn tiền nhất và hay bị nhầm nhất, đặc biệt với mô hình nhiều cửa hàng dùng chung một tài khoản ZBS.

Mã	Ý nghĩa	Cách xử lý
-115	Tài khoản ZBS không đủ số dư	Kiểm tra & nạp tiền vào ZBS Account trước khi gửi
-137	Trừ tiền ZBS Account thất bại	Kiểm tra số dư ZBS Account; thường do hết tiền giữa chừng
-136	Cần kết nối với ZBS Account	Liên kết ứng dụng (App) với ZBS Account của OA

Kinh nghiệm thực tế: nếu nhiều cửa hàng dùng chung một ZBS Account, một cửa hàng tiêu hết quỹ có thể khiến tất cả cùng gặp -137. Nên tách "ví ảo" theo từng cửa hàng để tính phí lại, đồng thời theo dõi số dư thật của ZBS Account ở cấp tổng để cảnh báo sớm.

Nhóm 2 — Lỗi quyền & template

Mã	Ý nghĩa	Cách xử lý
-117	OA/App chưa có quyền dùng template này	Kiểm tra AppID/OAID/templateID có khớp nhau không
-120	OA chưa mua gói dịch vụ để dùng tính năng	Mua/đăng ký gói tương ứng cho OA
-131	Template chưa được phê duyệt	Chỉ gửi template trạng thái ENABLE/đã duyệt
-135	OA chưa có quyền gửi tin qua SĐT (gói miễn phí, chưa xác thực)	Xác thực OA & nâng gói để mở quyền gửi SĐT

Nhóm 3 — Lỗi dữ liệu đầu vào

Mã	Ý nghĩa	Cách xử lý
-108	Số điện thoại không hợp lệ	Chuẩn hóa về dạng 84xxxxxxxxx
-118	Tài khoản Zalo không tồn tại/đã vô hiệu hóa	Bỏ qua hoặc gửi kênh khác; số không gắn Zalo
-1122	Thiếu tham số trong template_data	Bổ sung đủ biến mà template yêu cầu
-1124	Tham số sai định dạng	Truyền đúng format dữ liệu của từng biến

Nhóm 4 — Lỗi gửi qua UID & chuyển đổi từ ZNS

Lỗi -249 (Template does not support send via UID) là cái bẫy lớn nhất khi chuyển từ ZNS sang ZBS. Các template tạo trước 10/12/2025 (ZNS cũ), template OTP, template chứa component Response hay template Journey đều chưa hỗ trợ gửi qua UID.

Cách xử lý: tạo mới hoặc clone lại template theo chuẩn ZBS — gồm template tùy chỉnh, đánh giá dịch vụ, yêu cầu thanh toán và voucher. Đây là việc nên làm sớm để tận dụng kênh UID (rẻ hơn gửi qua số điện thoại trong nhiều trường hợp).

Checklist tránh lỗi khi tích hợp ZBS

1. Chống gửi trùng (idempotency)
Khóa theo (sự kiện + mã đơn) để mỗi sự kiện chỉ gửi một lần; chỉ kích hoạt khi trạng thái đơn thực sự đổi.
2. Chuẩn hóa số điện thoại
Đưa về 84xxxxxxxxx trước khi gọi API để tránh -108.
3. Chỉ dùng template đã duyệt
Lọc theo trạng thái ENABLE để tránh -131; kiểm tra khớp AppID/OAID/templateID để tránh -117.
4. Theo dõi số dư ZBS Account ở cấp tổng
Cảnh báo sớm khi sắp hết quỹ để tránh -115/-137 ảnh hưởng toàn bộ cửa hàng dùng chung.
5. Đối soát log gửi tin & chi phí
Ghi rõ tin nào đã tính phí; tách tin test ra khỏi báo cáo chi phí thực.

Câu hỏi thường gặp

Lỗi -137 khi gửi tin ZBS nghĩa là gì?

Là lỗi trừ tiền từ ZBS Account thất bại — thường do tài khoản ZBS không đủ số dư. ZBS Account giữ tiền thật để Zalo trừ phí mỗi tin gửi qua số điện thoại, khác với ví nội bộ của từng cửa hàng.

Lỗi -115 và -137 khác nhau thế nào?

-115 báo không đủ số dư trước khi gửi; -137 báo bước trừ tiền thất bại khi đang gửi. Cùng hướng xử lý: kiểm tra và nạp tiền vào ZBS Account.

Vì sao template cũ không gửi được qua UID (-249)?

Template tạo trước 10/12/2025, template OTP, template chứa component Response hoặc Journey chưa hỗ trợ UID. Cần tạo mới hoặc clone lại theo chuẩn ZBS.

Làm sao tránh gửi trùng tin và bị tính phí nhiều lần?

Dùng khóa idempotency theo (sự kiện + mã đơn) và chỉ gửi khi trạng thái thực sự đổi. tracking_id thường gắn timestamp nên Zalo không tự khử trùng — hệ thống của bạn phải tự đảm nhiệm.

Nguồn tham khảo mã lỗi: Zalo for Developers — Bảng mã lỗi ZBS Template Message. Nội dung phân tích & checklist do Zimo biên soạn từ kinh nghiệm tích hợp thực tế.

Cần tích hợp gửi tin ZBS đúng chuẩn, không lỗi vặt?

Zimo giúp doanh nghiệp kết nối OA, gửi tin ZBS tự động và đối soát chi phí minh bạch.

Nhận tư vấn miễn phí →

Lỗi gửi tin ZBS Template Message: Bảng mã lỗi & cách xử lý thực tế