ZNS API: gửi tin theo số điện thoại
ZNS gửi được tới bất kỳ số điện thoại nào, kể cả người chưa từng quan tâm OA của bạn — nên đây là kênh chính để báo đơn hàng. Tab này có ba phần: hạn mức tin, danh sách mẫu tin đã duyệt, và bảng bật/tắt từng mốc gửi tin.
Mở tab ZNS API
Vào Cài đặt → DevVN - Zalo OA → ZNS API.
- ZNS API — tab thứ hai.
- Số tin qua SĐT còn lại trong ngày — hạn mức Zalo cấp cho OA của bạn, đọc thẳng từ Zalo. Hết hạn mức là tin không gửi được nữa, dù plugin có cấu hình đúng.
- Danh sách template và Cấu hình gửi tin — hai mục con của tab này. Mặc định mở ở Danh sách template.
Danh sách template
Đây là các mẫu tin OA của bạn đã đăng ký và được Zalo duyệt. Plugin chỉ đọc, không tạo và không sửa được.
- Template ID — mã số của mẫu tin. Đây là thứ bạn chọn ở phần cấu hình bên dưới.
- Đơn giá — giá mỗi tin theo bảng giá Zalo, để bạn cân nhắc bật mốc nào.
- Xem chi tiết — mở nội dung mẫu và danh sách tham số mà mẫu đó cần. Bấm vào đây trước khi cấu hình, để biết mẫu cần những tham số nào.
Plugin lưu tạm danh sách mẫu để khỏi hỏi Zalo mỗi lần mở trang. Tải lại trang vài lần, hoặc quay sang tab Cài đặt chung bấm lại Get access token là danh sách được nạp lại.
Cấu hình gửi tin — phần trên
Bấm mục con Cấu hình gửi tin. Đây là nơi quyết định lúc nào website gửi tin.
- Chế độ development — chỉ gửi thử mẫu ZNS đến số điện thoại của quản trị viên ứng dụng hoặc quản trị viên OA. Không mất tiền. Bật khi đang thử; nhớ tắt khi chạy thật, không thì khách không bao giờ nhận được tin.
- Ưu tiên gửi qua UID — nếu số điện thoại của khách đã có UID trong danh sách người dùng OA, plugin sẽ gửi tin ZBS qua UID cho rẻ thay vì gửi ZNS. Nếu Zalo trả lỗi thì tự gửi lại bằng ZNS. Không áp dụng khi bật chế độ development và không áp dụng cho tin OTP.
- Gửi tin cho sđt admin OA khi có đơn hàng mới — báo cho chính bạn, không phải cho khách. Điền một hoặc nhiều số vào ô bên dưới, cách nhau dấu phẩy. Tin này luôn đi ở chế độ development nên không mất tiền.
- Khi có đơn hàng mới — mốc quan trọng nhất: khách vừa đặt hàng xong là nhận tin xác nhận.
Mỗi hàng trong bảng có bốn cột:
| Cột | Làm gì |
|---|---|
| Kích hoạt | Bật hay tắt mốc đó. Không tích thì mốc đó không gửi gì cả. |
| Hành động | Mô tả mốc gửi tin. Vài hàng có thêm ô để chọn trạng thái hoặc nhập số. |
| Chọn template | Mẫu tin dùng cho mốc này, lấy từ danh sách đã duyệt. |
| Tham số | Hiện ra sau khi bạn chọn template. Liệt kê các ô trống trong mẫu để bạn nối vào dữ liệu đơn hàng — xem mục dưới. |
Cấu hình gửi tin — phần dưới
- Khi có bất kỳ thay đổi trạng thái đơn hàng nào — gửi mỗi lần đơn đổi trạng thái, bất kể đổi sang gì. Tiện nhưng tốn tiền nhất; chỉ nên dùng khi mẫu tin của bạn ghi chung chung.
- Khi trạng thái đơn hàng thay đổi (Từ → đến) — chỉ gửi đúng một chặng bạn chọn, ví dụ từ Đang xử lý sang Đang giao hàng. Có hai hàng giống hệt nhau để bạn đặt hai chặng khác nhau với hai mẫu tin khác nhau.
- Khi đơn hoàn thành — gửi khi đơn chuyển sang trạng thái hoàn thành.
- Gửi tin nhắn đánh giá sản phẩm sau N ngày — nhắc khách đánh giá sau khi nhận hàng. Đơn có bao nhiêu sản phẩm thì gửi bấy nhiêu tin, và đánh giá khách gửi về sẽ tự thêm vào hệ thống đánh giá của WooCommerce qua webhook.
- Lưu thay đổi — bắt buộc bấm, nếu không mọi thứ vừa chỉnh đều mất.
Bật cùng lúc thì một lần đổi trạng thái khách nhận hai tin, và bạn trả tiền hai lần. Chọn một trong hai cách: hoặc gửi mọi lần đổi, hoặc chỉ gửi ở vài chặng cụ thể. Muốn bật cả hai mà không trùng thì dùng hook skip_send_zns_on_change_status ở bài Hook action và filter.
Nối tham số của mẫu tin với dữ liệu đơn hàng
Mẫu tin của Zalo có các ô trống, ví dụ customer_name, order_code, total. Cột Tham số liệt kê đúng những ô đó, và bạn điền vào mỗi ô một mã thay thế để plugin lấy dữ liệu thật từ đơn hàng.
| Mã thay thế | Lấy giá trị gì |
|---|---|
{order_id} | Mã đơn hàng |
{order_full_name} | Tên khách hàng |
{phone_number} | Số điện thoại khách hàng |
{address} | Địa chỉ của khách hàng |
{order_total} | Tổng tiền đơn hàng, dạng số thuần |
{order_total_view} | Tổng tiền đã định dạng. Không dùng cho mẫu ZNS — Zalo chỉ nhận số. |
{order_shipping_total} | Tổng tiền vận chuyển |
{order_status} | Trạng thái đơn hàng |
{order_create_date} | Ngày tạo đơn |
{product_name_zns} | Tên sản phẩm. Mẫu tin đánh giá thì không chọn cái này. |
{payment} | Hình thức thanh toán |
{note} | Ghi chú của khách hàng |
{order_key} | Order Key — dùng để dựng liên kết xem chi tiết đơn |
{order_view_detail} | Liên kết xem chi tiết đơn hàng |
{order_view_detail_urlencode} | Liên kết xem chi tiết đã mã hoá, không kèm tên miền |
Bạn cũng có thể gõ chữ cố định vào ô tham số nếu mẫu tin cần một giá trị không đổi, hoặc trộn chữ với mã thay thế. Cần một giá trị mà bảng trên không có thì tự thêm bằng hook mess_filter_content_<tên>, xem bài Hook action và filter.
Cách kiểm tra đã chạy đúng chưa
- Bật Chế độ development, chọn mẫu tin và điền tham số cho mốc Khi có đơn hàng mới, rồi Lưu thay đổi.
- Đặt một đơn thử trên website, dùng đúng số điện thoại của quản trị viên OA.
- Xem điện thoại có nhận được tin không, và nội dung có đúng tên, đúng mã đơn không.
- Mở tab Quản lý tin nhắn xem dòng vừa gửi và trạng thái của nó.
- Chạy ngon rồi thì tắt Chế độ development và đặt thêm một đơn thật để chốt.
Lỗi thường gặp
| Hiện tượng | Cách xử lý |
|---|---|
| Ô chọn template trống rỗng | OA chưa có mẫu tin nào được duyệt, hoặc access token đã hết hạn. Xem lại Kết nối Zalo OA. |
| Chọn template rồi mà cột Tham số vẫn trống | Chờ một nhịp — cột này nạp bằng AJAX. Vẫn trống thì mẫu tin đó không có tham số nào, hoặc trình duyệt đang chặn script. |
| Không nhận được tin nào | Kiểm tra theo thứ tự: đã tích Kích hoạt chưa · đã chọn template chưa · Chế độ development có đang bật không · hạn mức trên đầu tab còn không. |
| Tin gửi được nhưng thiếu chữ, hiện ô trống | Tham số chưa nối hoặc nối sai mã. Mở lại Xem chi tiết của mẫu để đối chiếu đúng tên tham số. |
| Zalo trả lỗi về giá trị tham số | Thường do dùng {order_total_view} cho ô cần số. Đổi sang {order_total}. |
| Khách nhận hai tin cho một lần đổi trạng thái | Đang bật cả mốc "bất kỳ thay đổi nào" lẫn mốc chặng cụ thể. Tắt bớt một. |
Muốn rẻ hơn: xem Tin ZBS gửi qua UID.