🔔 Thông báo Zalo ZNS

Zalo ZNS (Zalo Notification Service) giúp Xbook gửi tin giao dịch chính thức tới tài khoản Zalo của khách hàng — như xác nhận đơn hàng, nhắc lịch hay thông báo trạng thái — bằng các mẫu (template) đã được Zalo duyệt. Hệ thống đồng bộ mẫu ZNS từ Zalo OA, cho phép ánh xạ tham số từ dữ liệu nghiệp vụ (ví dụ đơn bán) rồi gửi tin thật tới khách.

💡 Phân hệ ZNS chạy trên nền kết nối Zalo OA. Bạn cần kết nối Zalo OA (lấy access_token) trước khi đồng bộ hoặc gửi ZNS.

📂 Truy cập phân hệ ZNS

Mở Zalo → ZNS trên thanh điều hướng. Phân hệ gồm các mục con:

Menu	Ý nghĩa
ZNS Templates	Danh sách mẫu ZNS đồng bộ từ Zalo, kèm tham số và nút
Message History	Lịch sử các tin ZNS đã gửi và trạng thái phát
OA Quality	Chất lượng gửi tin của OA (48 giờ và 7 ngày)
Quota	Hạn mức gửi tin theo ngày / tháng

📷 Cần chèn ảnh: /img/integrations/zalo-zns/01.png — Menu Zalo → ZNS với các mục con.

📥 Đồng bộ mẫu ZNS (zns_template)

Mẫu ZNS được tạo và duyệt phía Zalo, sau đó Xbook kéo về để sử dụng. Hệ thống đã có tác vụ tự động chạy định kỳ mỗi 60 phút để cập nhật danh sách mẫu; bạn cũng có thể đồng bộ thủ công.

Vào Zalo → ZNS → ZNS Templates.
Nhấn nút Fetch Templates ở đầu danh sách để tải toàn bộ mẫu từ Zalo về.
Mở một mẫu, nhấn Update để lấy chi tiết mới nhất (tham số, nút, dữ liệu mẫu).

Các trường chính của một mẫu ZNS:

Trường	Ý nghĩa
Template ID	Mã mẫu do Zalo cấp
Template Name	Tên mẫu
Status	Trạng thái duyệt: Enable, Pending Review, Deleted, Rejected, Disabled
Template Tag	Loại mẫu: Transaction, Customer Care, Promotion
Reason	Lý do (khi mẫu bị từ chối / vô hiệu)
Preview URL	Đường dẫn xem trước mẫu
Template Quality	Chất lượng mẫu
Price	Đơn giá mỗi tin
Timeout (ms)	Thời gian chờ
Model	Model nguồn dữ liệu để ánh xạ tham số (ví dụ đơn bán hàng)

💡 Chỉ mẫu ở trạng thái Enable mới được phép chọn khi gửi tin. Mẫu Pending Review, Rejected hay Disabled sẽ không xuất hiện trong danh sách chọn lúc gửi.

📷 Cần chèn ảnh: /img/integrations/zalo-zns/02.png — Danh sách ZNS Templates với nút Fetch Templates.

🔗 Ánh xạ tham số mẫu (zns_param)

Mỗi mẫu ZNS có các tham số (ví dụ tên khách, mã đơn, số tiền, ngày) cần được điền giá trị khi gửi. Xbook cho phép ánh xạ từng tham số vào một trường dữ liệu của model nguồn, để giá trị tự điền theo từng đơn hàng.

Mở mẫu cần cấu hình, chọn Model là model nguồn (ví dụ đơn bán hàng).
Vào tab Params trong mẫu.
Với mỗi tham số, chọn Field (trường dữ liệu) tương ứng; nếu cần đi sâu qua các quan hệ, nhập Field Path (ví dụ partner_id.name).
Cột Field Value hiển thị giá trị mẫu lấy thử để bạn kiểm tra ánh xạ.

Trường (tham số)	Ý nghĩa
Name	Tên tham số đúng theo mẫu Zalo (đồng bộ tự động, không sửa)
Require	Tham số bắt buộc hay không
Type	Kiểu dữ liệu của tham số
Field	Trường dữ liệu trong model nguồn được ánh xạ vào
Field Path	Đường dẫn mở rộng qua quan hệ, ví dụ `partner_id.name`
Field Value	Giá trị xem thử lấy từ một bản ghi mẫu
Sample Value	Giá trị mẫu do Zalo cung cấp

⚠️ Tên tham số (Name) và danh sách nút được đồng bộ từ Zalo và ở chế độ chỉ đọc. Khi mẫu thay đổi phía Zalo, hãy nhấn Update để cập nhật lại; phần ánh xạ Field / Field Path bạn đã thiết lập vẫn được giữ nguyên.

📷 Cần chèn ảnh: /img/integrations/zalo-zns/03.png — Tab Params với ánh xạ Field / Field Path.

🔘 Nút trong mẫu (zns_button)

Mẫu ZNS có thể đính kèm các nút (button) cho khách bấm. Các nút này được đồng bộ tự động từ Zalo và hiển thị ở tab Buttons trong mẫu (chỉ đọc), gồm: Type (loại nút — trang doanh nghiệp, gọi điện, trang thông tin OA, mini app, tải ứng dụng…), Title và Content.

📤 Gửi ZNS thật từ nghiệp vụ

Tin ZNS được gửi qua wizard gửi ZNS, lấy bối cảnh từ bản ghi nghiệp vụ đang chọn (ví dụ một đơn bán hàng). Wizard tự đổ các tham số của mẫu và điền giá trị theo ánh xạ đã cấu hình.

Chọn bản ghi nguồn (ví dụ một Đơn bán hàng) rồi mở wizard gửi ZNS trên bản ghi đó.
Trong cửa sổ Send ZNS, chọn Template — danh sách chỉ hiện mẫu ở trạng thái Enable và đúng model nguồn.
Kiểm tra Phone (số điện thoại khách); hệ thống tự chuẩn hóa về dạng 84....
Xem lại tab Params (các giá trị đã tự điền) và tab Buttons.
Nhấn:
- Send Dev — gửi ở chế độ thử nghiệm (development) để kiểm tra trước.
- Send ZNS — gửi tin thật tới khách hàng.

💡 Khi gửi từ đơn bán hàng, hệ thống tự gắn trạng thái đơn vào nội dung tin: đơn đã xác nhận hiển thị "Đã xác nhận", đơn đã hủy hiển thị "Đã hủy". Các tham số price (số tiền) và date (ngày, dạng dd/MM/yyyy) cũng được định dạng tự động.

⚠️ Send Dev chỉ dùng để kiểm thử; tin thật chỉ được gửi tới khách khi bạn nhấn Send ZNS. Hãy luôn thử Send Dev trước khi gửi hàng loạt.

Mỗi lần gửi thành công, hệ thống tạo một bản ghi trong Message History để bạn theo dõi.

📷 Cần chèn ảnh: /img/integrations/zalo-zns/04.png — Cửa sổ Send ZNS với tham số đã tự điền.

Gửi hàng loạt

Khi chọn nhiều bản ghi cùng lúc, wizard Send Multi ZNS cho phép gửi cho danh sách khách. Ngoài Send Dev và Send ZNS, wizard này có thêm nút Export JSON để xuất dữ liệu tham số của tất cả bản ghi ra file, tiện kiểm tra trước khi gửi.

📊 Theo dõi lịch sử, hạn mức và chất lượng

Lịch sử tin (Message History)

Vào Zalo → ZNS → Message History để xem các tin đã gửi. Mở một tin và nhấn Check Status để cập nhật trạng thái phát từ Zalo.

Trường	Ý nghĩa
Message ID	Mã tin do Zalo cấp
Phone	Số điện thoại nhận
Template	Mẫu ZNS đã dùng
Status	Trạng thái: Not Exist, Pending Delivery, Delivered
Status Message	Mô tả trạng thái
Delivery Time	Thời điểm phát tới khách
Send Time	Thời điểm gửi

Hạn mức (Quota / zns_quota)

Vào Zalo → ZNS → Quota, nhấn Fetch Quota để lấy hạn mức gửi tin hiện tại từ Zalo. Theo dõi các chỉ số: hạn mức ngày (Daily Quota / Remaining Quota), hạn mức khuyến mãi theo ngày và theo tháng (Daily / Monthly Promotion Quota và phần còn lại), cùng ước tính hạn mức khuyến mãi tháng kế tiếp.

Chất lượng OA (OA Quality / zns_quality)

Vào Zalo → ZNS → OA Quality để xem chất lượng gửi tin của OA: Current Quality (48h) và 7-day Quality, với mức High / Medium / Low / Undefined. Chất lượng thấp có thể ảnh hưởng tới hạn mức và khả năng gửi tin.

⚠️ Hạn mức (Quota) và chất lượng (OA Quality) do Zalo quản lý. Gửi tin sai mẫu, sai đối tượng hoặc bị khách phản hồi tiêu cực sẽ làm giảm chất lượng OA và hạn mức gửi tin.

Đánh giá của khách (zns_rating)

Khách hàng có thể đánh giá tin ZNS đã nhận. Trong một mẫu, nhấn Fetch Ratings để đồng bộ đánh giá; kết quả hiển thị ở tab Ratings với số sao (Stars), ghi chú (Note), phản hồi (Feedbacks) và ngày gửi đánh giá.

📷 Cần chèn ảnh: /img/integrations/zalo-zns/05.png — Màn hình Quota và OA Quality.

📂 Truy cập phân hệ ZNS​

📥 Đồng bộ mẫu ZNS (zns_template)​

🔗 Ánh xạ tham số mẫu (zns_param)​

🔘 Nút trong mẫu (zns_button)​

📤 Gửi ZNS thật từ nghiệp vụ​

Gửi hàng loạt​

📊 Theo dõi lịch sử, hạn mức và chất lượng​

Lịch sử tin (Message History)​

Hạn mức (Quota / zns_quota)​

Chất lượng OA (OA Quality / zns_quality)​

Đánh giá của khách (zns_rating)​

Liên quan​