Hướng dẫn Zalo OA & ZNS | BĐS Store

Tổng quan

Zalo OA và ZNS là gì?

Zalo OA (Official Account) là tài khoản doanh nghiệp trên Zalo. ZNS (Zalo Notification Service) là dịch vụ gửi tin nhắn chủ động tới khách hàng đã từng nhắn tin với OA — tỉ lệ đọc cao hơn SMS vì tin hiện trong ứng dụng Zalo quen thuộc.

ZNS khác gì Broadcast?

Broadcast gửi đại trà đến followers. ZNS gửi cá nhân hoá theo template đã duyệt — phù hợp cho thông báo giao dịch, nhắc lịch hẹn, chăm sóc khách.

Chi phí ZNS

Mỗi tin ZNS mất phí theo bảng giá Zalo (tính bằng ZNS Token, nạp qua business.zalo.me). Thông thường 100–500 đồng/tin tùy loại template.

Điều kiện người nhận

Người nhận phải có số điện thoại dùng tài khoản Zalo. Nếu không có Zalo, tin sẽ thất bại nhưng không bị tính phí.

Các bước thực hiện

1Drip follow-up ở bước kênh ZALO sẽ tự gọi API ZNS với template bạn cấu hình.
2Hệ thống chuẩn hóa SĐT về dạng 84xxxxxxxxx trước khi gửi.
3Token tự động refresh trước khi hết hạn (Zalo Access Token hết hạn sau ~1 giờ, Refresh Token dùng được nhiều tháng).

💡

ZNS phù hợp nhất cho bước follow-up thứ 2 (sau 72h kể từ khi có lead) — khách đã biết bạn từ bước gọi điện đầu, tin ZNS sẽ ít bị coi là spam hơn.

Bước 1

Đăng ký và xác minh Zalo OA

Bạn cần một Zalo Official Account đã được xác minh. OA cá nhân (chưa xác minh) có hạn chế nhất định về ZNS.

OA cá nhân vs doanh nghiệp

OA cá nhân (xác minh CMND/CCCD) đủ dùng cho môi giới cá nhân. OA doanh nghiệp (xác minh giấy phép kinh doanh) có hạn mức ZNS cao hơn.

Tên OA

Đặt tên OA chuyên nghiệp (ví dụ: 'Nguyễn Văn A – Môi giới BĐS Vinhomes'). Khách sẽ thấy tên này khi nhận tin ZNS.

Thời gian duyệt

Đăng ký OA mới mất 1–3 ngày làm việc để Zalo duyệt. Lên kế hoạch trước.

Các bước thực hiện

1Truy cập oa.zalo.me → đăng nhập bằng tài khoản Zalo cá nhân.
2Chọn 'Tạo OA mới' → điền tên, lĩnh vực (Bất động sản), mô tả.
3Upload logo và ảnh bìa chuyên nghiệp.
4Xác minh danh tính: chụp CMND/CCCD hoặc tải giấy phép kinh doanh.
5Chờ email xác nhận từ Zalo (1–3 ngày làm việc).
6Sau khi được duyệt, OA của bạn sẽ có tick xanh hoặc tick vàng.

💡

Trong lúc chờ OA được duyệt, bạn có thể làm song song Bước 2 (tạo Zalo App) vì App không cần chờ OA được duyệt.

Bước 2

Tạo Zalo App trên Developers Portal

Zalo App là credential cho phép server gọi Zalo Business API. Một App gán với một OA.

App ID & Secret Key

Sau khi tạo App, bạn nhận được App ID và Secret Key. Đây là credentials cần nhập vào BĐS Store.

Kích hoạt Zalo Business API

Trong App settings, phải enable 'Zalo Business API' / 'Official Account API' thì mới gọi được ZNS.

Gắn OA vào App

Trong App settings → Official Account → gắn OA ID của bạn. Đây là liên kết giữa App credentials và OA thực tế.

Các bước thực hiện

1Truy cập developers.zalo.me → đăng nhập.
2Bấm 'Tạo ứng dụng mới' → điền tên App (ví dụ: BDS Store Integration).
3Sau khi tạo, vào tab 'Sản phẩm' → tìm 'Zalo Official Account API' → bấm 'Sử dụng ngay'.
4Vào tab 'Cấu hình' → mục 'Official Account' → nhập OA ID của bạn (lấy từ oa.zalo.me → Cài đặt → Thông tin OA).
5Lưu lại App ID và Secret Key — cần dùng ở bước tiếp theo.

💡

OA ID thường có dạng số dài, ví dụ: 579745863880352716. Tìm trong oa.zalo.me → Cài đặt OA → Thông tin OA → 'ID OA'.

Bước 3

Lấy Access Token và Refresh Token

Zalo dùng OAuth 2.0. Access Token hết hạn sau ~1 giờ, Refresh Token dùng được lâu hơn. BĐS Store tự động refresh token khi sắp hết hạn.

Authorization Code Flow

Phải mở trình duyệt để đăng nhập Zalo lần đầu, lấy authorization code. Sau đó đổi code lấy Access Token + Refresh Token.

Auto-refresh

BĐS Store tự refresh trước khi hết hạn 5 phút. Nếu refresh thất bại (Refresh Token hết hạn hoặc bị thu hồi), OA sẽ bị đánh dấu inactive và cần lấy token mới.

Bảo mật

Secret Key và Access/Refresh Token được lưu mã hoá trong database. Không chia sẻ các giá trị này.

Các bước thực hiện

1Mở URL sau trong trình duyệt (thay APP_ID bằng App ID của bạn):
2 https://oauth.zaloapp.com/v4/oa/permission?app_id={APP_ID}&redirect_uri=https://zalo.me
3Đăng nhập bằng tài khoản Zalo Admin của OA → cấp quyền.
4Sau khi redirect, URL chứa code=xxxxx — copy giá trị code đó.
5Đổi code lấy token:
6 POST https://oauth.zaloapp.com/v4/oa/access_token
7 app_id={APP_ID} & code={CODE} & grant_type=authorization_code
8 Header: secret_key: {SECRET_KEY}
9Response chứa access_token, refresh_token, expires_in.

# Bước 1: Mở URL này trong trình duyệt (thay APP_ID)
https://oauth.zaloapp.com/v4/oa/permission?app_id={APP_ID}&redirect_uri=https://zalo.me

# Bước 2: Sau khi redirect, lấy code từ URL: ?code=XXXXX
# Bước 3: Đổi code lấy token (chạy trong terminal)
curl -X POST https://oauth.zaloapp.com/v4/oa/access_token \
  -H "secret_key: {SECRET_KEY}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "app_id={APP_ID}&code={CODE}&grant_type=authorization_code"

# Response mẫu:
# {
#   "access_token": "xxx...",
#   "refresh_token": "yyy...",
#   "expires_in": "3600"
# }

⚠️

Authorization Code chỉ dùng được 1 lần và hết hạn sau vài phút. Phải đổi sang token ngay sau khi lấy code.

Bước 4

Nhập cấu hình vào Dashboard

Sau khi có đủ credentials, nhập vào BĐS Store để hệ thống có thể gửi ZNS thay bạn.

OA ID

ID của Official Account (chuỗi số). Tìm trong oa.zalo.me → Cài đặt → Thông tin OA.

App ID + Secret Key

Lấy từ developers.zalo.me → App của bạn → tab Cài đặt.

Access Token + Refresh Token

Lấy từ Bước 3. Khi lưu, hệ thống sẽ tự set tokenExpiresAt = now + 1 giờ để biết khi nào cần refresh.

Các bước thực hiện

1Vào Dashboard → Cài đặt → Zalo OA.
2Điền OA ID, Tên OA (để dễ nhận ra), App ID, Secret Key.
3Dán Access Token và Refresh Token vừa lấy.
4Bấm 'Lưu cấu hình'.
5Bấm 'Kiểm tra kết nối' — hệ thống sẽ gọi refresh API để xác nhận credentials đúng.
6Nếu OK: hiện thông báo xanh và expiresAt của token mới.

💡

Nút 'Kiểm tra kết nối' thực ra gọi refresh token ngay — nếu thành công, token được cập nhật và thời gian hết hạn được reset về +1 giờ.

Mở Cài đặt Zalo OA →

Bước 5

Tạo và xin duyệt Template ZNS

ZNS bắt buộc phải dùng template đã được Zalo duyệt trước. Không thể gửi tin tự do. Thời gian duyệt template thường 1–3 ngày.

Loại template phù hợp

Chọn loại 'Chăm sóc khách hàng' hoặc 'Thông báo giao dịch'. Tránh loại quảng cáo/khuyến mãi vì khó được duyệt hơn.

Biến trong template

Dùng {{variable_name}} cho các trường thay đổi theo từng lead (ví dụ: {{customer_name}}, {{project_name}}, {{agent_phone}}). Khi gửi, truyền vào template_data.

Ví dụ template follow-up BĐS

Xin chào {{customer_name}}, tôi là {{agent_name}} — tư vấn viên dự án {{project_name}}. Tôi đã gọi điện cho bạn nhưng chưa kết nối được. Bạn có thể gọi lại {{agent_phone}} hoặc nhắn tin tại đây để tôi hỗ trợ nhé.

Các bước thực hiện

1Truy cập business.zalo.me → đăng nhập bằng tài khoản Admin của OA.
2Vào 'Zalo Notification Service' → 'Quản lý template' → 'Tạo template mới'.
3Chọn loại template, điền tên và nội dung (dùng {{biến}} cho các trường động).
4Preview để xem trước → Submit để gửi duyệt.
5Sau khi được duyệt, vào OA Settings → lấy Template ID (chuỗi số).
6Quay lại Dashboard BĐS Store → Cài đặt → Zalo OA → Thêm template → nhập Template ID + tên gọi nhớ.

// Ví dụ template_data khi gửi ZNS
// Template: "Xin chào {{customer_name}}, tôi là {{agent_name}}..."

{
  "customer_name": "Nguyễn Văn A",
  "agent_name": "Trần Thị B",
  "project_name": "Vinhomes Hạ Long Xanh",
  "agent_phone": "0901234567"
}

💡

Tên biến trong template phải viết thường, không dấu, dùng dấu gạch dưới (underscore). Ví dụ: {{customer_name}} không phải {{Tên khách}}.

Bước 6

Cấu hình Drip gửi ZNS tự động

Sau khi có template ZNS được duyệt, cấu hình bước drip kênh Zalo để hệ thống tự động gửi khi đến hạn.

Chọn kênh ZALO

Trong Cài đặt → Kịch bản Drip → chọn bước muốn gửi Zalo → đổi kênh thành 'Zalo'.

Gắn template

Mỗi bước drip kênh Zalo cần chọn template ZNS. Hệ thống tự map thông tin lead vào các biến {{customer_name}}, {{agent_name}} v.v.

Fallback

Nếu khách không có Zalo hoặc gửi thất bại, task sẽ báo lỗi trong drawer lead để bạn chuyển sang kênh khác.

Các bước thực hiện

1Dashboard → Cài đặt → Kịch bản Drip.
2Tìm bước muốn gửi Zalo (thường là bước 2, sau 72h).
3Đổi kênh thành 'Zalo' → chọn ZNS Template từ dropdown.
4Lưu kịch bản.
5Test: tạo một lead mới → mở drawer → xem bước Zalo → bấm 'Gửi tự động' (không cần đợi đến hạn).

💡

BĐS Store tự động điền các biến chuẩn: customer_name (từ lead.name), agent_name (từ profile user), project_name (từ dự án của lead). Bạn chỉ cần tạo template dùng đúng tên biến này.

Mở Cài đặt Drip →

Vận hành

Theo dõi và xử lý sự cố

Hệ thống ZNS có nhiều lý do thất bại. Biết cách đọc lỗi giúp xử lý nhanh hơn.

Error -201: Token hết hạn

Refresh Token hết hạn hoặc bị thu hồi — cần lấy Authorization Code mới (Bước 3) và cập nhật lại token trong Cài đặt.

Error -124: Số không dùng Zalo

Khách không có tài khoản Zalo với số điện thoại đó. Không tính phí. Chuyển sang kênh SMS hoặc Email.

Error -216: Vượt quota

Hết ZNS Token trong tháng. Nạp thêm tại business.zalo.me hoặc chờ tháng sau quota được reset.

Các bước thực hiện

1Dashboard → Cài đặt → Zalo OA → xem trường 'Lỗi gần nhất' và 'Đã gửi tháng này'.
2Nếu trạng thái OA là 'Inactive': kiểm tra lastError, thường do token hết hạn.
3Để refresh token thủ công: bấm 'Kiểm tra kết nối' — nếu Refresh Token còn hiệu lực sẽ tự lấy token mới.
4Theo dõi quota ZNS tại business.zalo.me → ZNS → Thống kê.

Kiểm tra Zalo OA →

Zalo OA & ZNS

Zalo OA và ZNS là gì?

Đăng ký và xác minh Zalo OA

Tạo Zalo App trên Developers Portal

Lấy Access Token và Refresh Token

Nhập cấu hình vào Dashboard

Tạo và xin duyệt Template ZNS

Cấu hình Drip gửi ZNS tự động

Theo dõi và xử lý sự cố

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

Sẵn sàng setup Zalo OA?