📖 Hướng dẫn sử dụng
Javis Zalo ZNS
Plugin v3.5.2
Kết nối Zalo Official Account với WooCommerce & Javis BookingPro — gửi thông báo tự động qua ZNS (mọi SĐT) và ZBS (follower OA).
📑 Mục lục
1. Yêu cầu hệ thống
| Thành phần | Yêu cầu tối thiểu | Khuyến nghị |
|---|---|---|
| PHP | 7.4+ | 8.1+ |
| WordPress | 6.0+ | 6.4+ |
| WooCommerce | 7.0+ (nếu dùng WC) | 8.x – 9.x |
| Javis BookingPro | Bất kỳ (nếu dùng Booking) | Mới nhất |
| Zalo App | Đã tạo tại developers.zalo.me | — |
| Zalo OA | Official Account đã verify | OA đã bật ZNS |
| Cron | WP-Cron hoặc Server Cron | Server Cron (chính xác hơn) |
Plugin hoạt động độc lập — chỉ cần một trong hai: WooCommerce hoặc Javis BookingPro. Không cần cả hai.
2. Cài đặt & Kích hoạt
-
Vào WordPress Admin → Plugins → Add New → Upload Plugin.
-
Chọn file javis-zalo-zns-v3.5.2.zip → nhấn Install Now.
-
Sau khi cài xong, nhấn Activate Plugin.
-
Plugin tự tạo bảng database và lên lịch cron. Vào WP Admin → Zalo OA trong menu trái để tiếp tục cấu hình.
Sau khi activate, kiểm tra menu Zalo OA xuất hiện trong WordPress Admin sidebar. Nếu không thấy, thử deactivate & activate lại.
Nâng cấp từ phiên bản cũ: Deactivate bản cũ → xóa → upload & activate bản mới. Plugin tự migrate database khi activate.
3. Kết nối Zalo OA
Vào Zalo OA → Cài đặt. Có 2 cách lấy token:
⭐ Cách 1 — Lấy token thủ công (Khuyến nghị)
- Vào developers.zalo.me → chọn App của bạn.
- Click tab Official Account (menu bên trái).
- Tìm mục OA Access Token → click Tạo mới.
- Copy Access Token (hạn 90 ngày) và Refresh Token.
- Paste vào 2 field tương ứng trong plugin → nhấn Lưu cài đặt.
Plugin tự động refresh token mỗi ngày qua cron — bạn chỉ cần paste 1 lần, không cần làm lại mỗi 90 ngày (trừ khi Refresh Token hết hạn).
🔄 Cách 2 — OAuth tự động
- Điền App ID & App Secret vào form bên dưới → Lưu.
- Vào developers.zalo.me → App → tab Official Account → thêm Callback URL = URL được hiển thị trong plugin.
- Quay lại plugin → nhấn 🔑 Kết nối Zalo OA → xác nhận trên Zalo.
📋 Các thông tin cần điền
| Field | Lấy ở đâu | Bắt buộc |
|---|---|---|
| OA ID | Zalo Business → Official Account → OA Info → OA ID | ✅ Bắt buộc |
| App ID | developers.zalo.me → App → App Info | Chỉ cần cho OAuth |
| App Secret | developers.zalo.me → App → App Info | Chỉ cần cho OAuth |
| Access Token | developers.zalo.me → App → Official Account → OA Access Token | ✅ Bắt buộc |
| Refresh Token | Lấy cùng chỗ với Access Token | Khuyến nghị |
Sau khi lưu, nhấn 🔍 Kiểm tra kết nối trong plugin để xác nhận token hợp lệ và lấy thông tin OA.
4. Cấu hình ZNS — WooCommerce
Vào Zalo OA → ZNS. Mỗi sự kiện WooCommerce cần một ZNS Template ID đã được Zalo duyệt.
ZNS Template phải được Zalo duyệt trước tại business.zalo.me. Template chưa duyệt sẽ báo lỗi khi gửi.
⚡ Các sự kiện WooCommerce
Đơn hàng mới
Gửi ngay khi đơn hàng được tạo (pending / processing).
order_id, customer_name, order_total, products, phone
Thay đổi trạng thái
Gửi mỗi khi trạng thái đơn hàng thay đổi.
+ old_status, new_status, trang_thai_cu, trang_thai_moi
Đơn hoàn thành
Khi đơn chuyển sang “completed”.
Tất cả biến WooCommerce
Nhắc đánh giá
Gửi tự động sau khi đơn hoàn thành (cron).
+ review_url, link_danh_gia
🔄 Template theo từng trạng thái (Per-Status)
Ngoài 4 sự kiện chính, bạn có thể cấu hình template riêng cho từng trạng thái WooCommerce (vd: chỉ gửi khi on-hold, hoặc refunded). Kéo xuống phần Per-Status Template trong tab ZNS.
📤 Tải danh sách Template
- Nhấn 🔄 Tải danh sách ZNS Template để lấy danh sách template từ Zalo.
- Copy Template ID từ bảng hiện ra.
- Paste vào field tương ứng của từng sự kiện.
- Nhấn Lưu cài đặt ZNS.
🔬 Gửi thử (Test)
Mỗi sự kiện có nút 🔬 Test (biểu tượng kính lúp). Nhấn → nhập SĐT → nhấn Gửi thử để kiểm tra template hoạt động đúng.
5. Booking Workflows — Javis BookingPro
Vào Zalo OA → Booking Workflows. Plugin tự detect Javis BookingPro — cấu hình sẵn ở đây, sẽ tự chạy khi plugin booking được kích hoạt.
⚡ Sự kiện realtime
Đặt mới
Gửi ngay khi khách submit form đặt bàn.
booking_ref, customer_name, booking_date, booking_time, guests, restaurant_name
Xác nhận
Khi booking chuyển trạng thái “confirmed”.
booking_ref, customer_name, booking_date, booking_time, table_number
Hủy đặt
Khi booking bị hủy hoặc no-show.
booking_ref, customer_name, booking_date
Thanh toán
Khi xác nhận thanh toán (VietQR / Stripe / PayPal).
customer_name, booking_ref, amount, booking_date
Check-in
Khi nhân viên check-in khách (thêm biến checkin_time).
customer_name, table_number, checkin_time
⏱ Tự động theo lịch (Cron)
Nhắc 3 ngày
Gửi tự động trước 72h (hourly cron).
customer_name, booking_ref, booking_date, booking_time, guests
Nhắc 1 ngày
Gửi tự động trước 24h.
customer_name, booking_ref, booking_date, booking_time
Nhắc 6 giờ
Nhắc lần cuối trước 6h.
customer_name, booking_ref, booking_date, booking_time
Win-back
Gửi cho khách hủy 7 ngày trước chưa đặt lại.
customer_name, restaurant_name, booking_url
Khảo sát
Sau booking hoàn thành (cron hourly). Cần điền Survey URL.
customer_name, booking_ref, restaurant_name, survey_url
Khuyến mãi
Blast khuyến mãi tới khách cũ (daily cron). Cần điền tiêu đề, URL, hạn dùng.
customer_name, promotion_title, promo_url, valid_until
👤 Thông báo Admin
Bật toggle Thông báo Admin → điền SĐT admin và template ID riêng → mỗi khi có booking mới, admin sẽ nhận ZNS ngay lập tức.
6. Param Mapping — Map biến
Mỗi ZNS Template trên Zalo có tên biến riêng (vd: ten_khach). Param Mapping cho phép bạn map biến Zalo → biến plugin mà không cần sửa code.
📝 Cú pháp
Mapping format (1 dòng = 1 map)
# Dòng comment bắt đầu bằng # ten_khach = customer_name ngay_hen = booking_date gio_hen = booking_time ma_dat_cho = booking_ref so_tien = amount_raw # Nhiều plugin key (dùng key đầu tiên có giá trị) sdt = phone , so_dien_thoai , sdt_kh # Giá trị cố định (literal) ten_nha_hang = Nhà Hàng ABC
Ví dụ thực tế: Template Zalo của bạn dùng biến {{ten_khach}} nhưng plugin cung cấp customer_name — bạn map:
ten_khach = customer_name
ten_khach = customer_name
📍 Vị trí cấu hình Mapping
| Workflow | Vị trí trong plugin |
|---|---|
| WooCommerce — Đơn hàng mới | ZNS → Param Mapping → Đơn hàng mới |
| WooCommerce — Thay đổi trạng thái | ZNS → Param Mapping → Thay đổi trạng thái |
| WooCommerce — Hoàn thành / Đánh giá | ZNS → Param Mapping → tương ứng |
| Booking — Đặt mới | Booking Workflows → Param Mapping → Đặt mới |
| Booking — tất cả events | Booking Workflows → từng card có ô Param Mapping |
| Global (áp dụng tất cả WC) | ZNS → Param Mapping → Global |
Mẹo: Dùng biến Vietnamese alias (vd: ten_kh, ngay_dat) thay vì mapping — đỡ phải viết mapping nếu template Zalo dùng đúng tên đó.
7. Bảng biến — Javis Booking Pro
Tất cả biến bên dưới dùng được trong template ZNS cho mọi workflow booking (trừ các biến có ghi chú riêng).
🏨 Javis Booking Pro
Biến Javis Booking Pro
Đầy đủ biến tiếng Anh + alias tiếng Việt cho mọi template ZNS booking
👤 Thông tin khách hàng
customer_name
ten_kh
ho_ten
phone
so_dien_thoai
sdt
📋 Thông tin đặt bàn
booking_ref
ma_dat_ban
ma_booking
booking_number
status
special_requests
📅 Ngày & Giờ
booking_date
ngay_dat
ngay
booking_time
gio_dat
gio
end_time
gio_ket_thuc
gio_ra
checkin_time ⚡
🪑 Bàn & Số khách
guests
so_nguoi
table_number
so_ban
ten_ban
🍽 Dịch vụ & Gói & Ca
service_name
ten_dich_vu
dich_vu
package
goi_dich_vu
ten_goi
slot_name
ten_ca
ten_khung_gio
💰 Thanh toán
amount
so_tien_fmt
tong_tien_fmt
amount_raw
so_tien
tong_tien
🏢 Nhà hàng & Liên kết
restaurant_name
nha_hang
ten_nha_hang
booking_url
⚙️ Biến thêm theo từng workflow
survey_url
link_khao_sat
promotion_title
tieu_de_khuyen_mai
promotion_desc
mo_ta
promo_url
link_uu_dai
valid_until
han_su_dung
🔵 Xanh đậm = tiếng Anh
🟢 Xanh lá = tiếng Việt (alias)
🟠 Cam = biến riêng theo workflow
📖 Giải thích chi tiết các biến quan trọng
| Biến | Mô tả | Ví dụ giá trị |
|---|---|---|
| booking_ref | Mã đặt bàn (booking reference hoặc #ID) | BK-2025-001 |
| booking_date | Ngày đặt bàn, format dd/mm/yyyy | 28/05/2025 |
| booking_time | Giờ đặt bàn, format HH:mm | 19:30 |
| end_time | Giờ kết thúc, format HH:mm | 21:00 |
| checkin_time | Giờ check-in thực tế (chỉ có trong sự kiện Check-in) | 19:35 |
| amount | Số tiền định dạng có đơn vị | 500,000đ |
| amount_raw | Số tiền nguyên không format — dùng cho ZNS param kiểu number | 500000 |
| slot_name | Tên ca làm việc / khung giờ (từ bảng rbp_timeslots) | Ca tối |
| service_name | Tên dịch vụ (từ bảng rbp_services) | Tiệc sinh nhật |
| package | Tên gói / buffet package | Buffet 299k |
8. Bảng biến — WooCommerce
🛒 WooCommerce
Biến WooCommerce — Đơn hàng
Dùng trong ZNS / ZBS workflow đơn hàng. Tất cả biến có sẵn trong mọi sự kiện WC.
👤 Khách hàng
customer_name
ten_kh
ho_ten
phone
sdt
sdt_kh
so_dien_thoai
dien_thoai
so_dt
mobile
📦 Đơn hàng
order_id
ma_don
order_number
ma_don_hang
order_status
trang_thai
order_date
ngay_dat
order_url
link_don_hang
note
ghi_chu
💳 Thanh toán & Tổng tiền
order_total
tong_tien
order_total_raw
tong_tien_raw
payment_method
phuong_thuc_tt
thanh_toan
hinh_thuc_tt
🛍 Sản phẩm
products
san_pham
so_luong_kh
so_luong
so_san_pham
🏪 Cửa hàng & Địa chỉ
shop_name
ten_cua_hang
cua_hang
shipping_address
dia_chi
🔄 Biến thêm — Thay đổi trạng thái
old_status
trang_thai_cu
new_status
trang_thai_moi
⭐ Biến thêm — Nhắc đánh giá
review_url
link_danh_gia
🟣 Tím đậm = tiếng Anh
🟣 Tím nhạt = tiếng Việt (alias)
9. Campaigns — ZBS Broadcast
Vào Zalo OA → Campaigns để gửi tin hàng loạt qua ZBS tới danh sách follower của OA.
ZBS chỉ gửi được cho follower OA (người đã quan tâm OA). Khác với ZNS có thể gửi mọi SĐT.
- Vào Campaigns → Tạo chiến dịch mới.
- Chọn Danh sách số điện thoại (nhập tay hoặc upload CSV).
- Điền nội dung tin nhắn ZBS (text + nút bấm).
- Đặt thời gian gửi (ngay hoặc lên lịch).
- Nhấn Lưu & Chạy.
Campaign ZBS không cần template được duyệt — nhưng nội dung phải tuân theo chính sách Zalo OA. Không spam, không quảng cáo quá mức.
10. Log & Theo dõi
Vào Zalo OA → Log để xem lịch sử gửi tin.
| Cột | Ý nghĩa |
|---|---|
| Thời gian | Thời điểm tin được gửi |
| SĐT | Số điện thoại nhận |
| Sự kiện | Workflow trigger (vd: bk_new_booking, wc_new_order) |
| Template | Template ID đã dùng |
| Kênh | ZNS hoặc ZBS |
| Trạng thái | sent / failed / queued |
| Phản hồi | Kết quả từ Zalo API (error code nếu thất bại) |
🔧 Xử lý lỗi phổ biến
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| -201 | Access Token hết hạn hoặc không hợp lệ | Lấy token mới → Cài đặt → Lưu |
| -124 | Số điện thoại không đúng định dạng | Kiểm tra SĐT khách hàng, đảm bảo đầu 84 hoặc 0 |
| -216 | Template chưa được duyệt hoặc sai ID | Kiểm tra template tại business.zalo.me, copy lại ID |
| -1 | Lỗi chung từ Zalo API | Kiểm tra log chi tiết, thử gửi lại sau vài phút |
| Không gửi được dù cấu hình đúng | WP-Cron không chạy (hosting chặn) | Dùng Server Cron: */5 * * * * wp cron event run –due-now |
11. Câu hỏi thường gặp
ZNS và ZBS khác nhau thế nào?
ZNS (Zalo Notification Service) gửi được tới mọi SĐT Zalo kể cả chưa quan tâm OA — nhưng cần template được Zalo duyệt và tốn 1 quota mỗi tin.
ZBS (Zalo Broadcast System) chỉ gửi cho follower đã quan tâm OA — không cần template duyệt, linh hoạt hơn về nội dung.
ZBS (Zalo Broadcast System) chỉ gửi cho follower đã quan tâm OA — không cần template duyệt, linh hoạt hơn về nội dung.
Template ZNS phải làm gì để được duyệt?
Tạo template tại business.zalo.me → Official Account → ZNS. Template cần: nội dung liên quan đến giao dịch, không quảng cáo, biến phải khớp tên. Thời gian duyệt thường 1-3 ngày làm việc.
Biến trong template không hiển thị đúng — làm sao sửa?
Dùng Param Mapping để map tên biến Zalo → tên biến plugin. Ví dụ nếu template Zalo dùng {{ten_khach_hang}} nhưng plugin có customer_name: viết ten_khach_hang = customer_name trong ô Param Mapping của sự kiện tương ứng.
Tin nhắc lịch (3 ngày, 1 ngày, 6 giờ) không tự gửi?
Các reminder dùng WP-Cron chạy mỗi giờ. Nếu site ít traffic, WP-Cron có thể không chạy đúng giờ. Giải pháp: dùng server cron gọi WordPress cron định kỳ, hoặc dùng plugin như WP Crontrol để kiểm tra.
Dùng amount hay amount_raw cho template ZNS?
amount — giá trị dạng text có định dạng: 500,000đ — dùng cho biến kiểu text trong ZNS.
amount_raw — số nguyên: 500000 — dùng cho biến kiểu number trong ZNS (yêu cầu phải là số).
amount_raw — số nguyên: 500000 — dùng cho biến kiểu number trong ZNS (yêu cầu phải là số).
Có thể dùng cả ZNS và ZBS cùng lúc không?
Có! Chọn kênh Cả hai (ZBS→ZNS) trong cài đặt — plugin gửi ZBS trước (cho follower), nếu lỗi thì fallback sang ZNS.
Plugin có hoạt động khi chỉ cài một trong hai (WooCommerce hoặc BookingPro)?
Hoàn toàn có! Plugin tự detect từng phần. Nếu chỉ có WooCommerce → chỉ WC workflow chạy. Nếu chỉ có BookingPro → chỉ Booking workflow chạy. Hai phần hoàn toàn độc lập.