Zalo ZNS

ZNS (Zalo Notification Service) gửi một tin nhắn theo mẫu tới số điện thoại qua Zalo Official Account (OA) của bạn. Khách không cần nhắn cho bạn trước, nên ZNS rất hợp để xác nhận đơn hàng, nhắc thanh toán hay báo tình trạng giao hàng. Bạn gửi ZNS được từ trang đơn hàng, tới một danh sách khách hàng đã lọc, từ chu trình, hoặc qua API. Zalo tính phí theo từng tin.

Trước khi bắt đầu

Kết nối Zalo Official Account ở Hỗ trợ → Kênh. Xem Zalo OA. Dashboard chỉ cho chọn tài khoản đang ở trạng thái Đang hoạt động.
Nâng OA lên gói trả phí của Zalo có ZNS. Nếu chưa, Hạ Tầng không tải được mẫu tin của bạn.
Tạo mẫu và chờ duyệt trong trang quản trị Zalo OA: oa.zalo.me → ZNS → Mẫu. Hạ Tầng chỉ liệt kê mẫu đã được duyệt.
Giữ module Khách hàng (CRM) đang bật. ZNS thuộc module Khách hàng: các endpoint API nằm trong module này, và tin đang xếp hàng bị bỏ qua khi module tắt. Xem Doanh nghiệp và module.

Trang Zalo ZNS

Vào Hỗ trợ → Kênh. Thẻ Zalo ZNS có nút Cài đặt ZNS mở trang Zalo ZNS. Trang này cho OA đang chọn hiển thị:

Hạn mức hôm nay: số tin còn được gửi trong ngày trên tổng hạn mức của OA.
Tổng số tin đã gửi, thất bại và đang trong hàng đợi.
Các mẫu đã duyệt với tên, id, trạng thái, chất lượng và giá mỗi tin.
Gửi gần đây với thời gian, số điện thoại, mẫu, trạng thái (kèm lỗi của Zalo khi thất bại) và liên kết tới đơn hàng, khách hàng.

Nếu doanh nghiệp có nhiều OA, chọn OA ở đầu trang.

Gửi thông báo cho một đơn hàng

Mở đơn hàng (Đơn hàng, rồi chọn đơn).
Trên thẻ Zalo ZNS, bấm Gửi thông báo.
Chọn OA và mẫu tin. Số điện thoại lấy từ địa chỉ giao hàng của đơn; phải là số di động Việt Nam.
Điền tham số của mẫu. Hạ Tầng tự điền sẵn các tham số có tên gợi ý tới tên khách, mã đơn, tổng tiền hoặc số điện thoại.
Bấm Gửi ZNS.

Tin được gửi ngay. Thẻ hiện Đã gửi (msg …) với mã tin của Zalo, hoặc lỗi Zalo trả về.

Gửi cho danh sách khách hàng

Vào Khách hàng và lọc danh sách (tìm kiếm, giai đoạn, người phụ trách, nhãn, kênh).
Bấm Gửi ZNS (trang này cũng có trên thanh bên với tên Gửi ZNS).
Chọn OA, mẫu tin và Số tin tối đa (tối đa 5.000).

Gán giá trị cho từng Tham số của mẫu:

Giá trị	Ý nghĩa
`customer.name`, `customer.phone`, `customer.email`	Thông tin của khách
`field:<key>`	Một trường tuỳ chỉnh, ví dụ `field:member_tier`
`text:` và văn bản cố định phía sau	Cùng một nội dung cho mọi người, ví dụ `text:20/11`

Kiểm tra số lượng: trang cho biết bao nhiêu khách khớp bộ lọc và bao nhiêu khách có số điện thoại. Rồi bấm Xếp hàng N tin ZNS.

Khách không có số điện thoại bị bỏ qua. Tin trong hàng đợi được gửi theo tốc độ của OA, kết quả hiện ở mục Gửi gần đây trên trang Zalo ZNS. Tin bị Zalo giới hạn tốc độ được thử lại, tối đa 3 lần.

cẩn thận

Zalo tính phí mỗi tin. Kiểm tra số người nhận và giá của mẫu trước khi xếp hàng một đợt gửi lớn.

Gửi từ chu trình

Thêm bước Gửi ZNS vào một chu trình, ví dụ với sự kiện Đơn đã thanh toán. Chọn OA, nhập Mã mẫu ZNS và tham số, mỗi dòng một cặp tên=giá trị. Giá trị dùng được {{name}}, {{phone}}, {{email}}, {{order_code}}, {{order_total}}, {{rating}} và {{site}}. Bước này dùng số điện thoại của khách và bị bỏ qua khi khách chưa có số.

Gửi qua API

Endpoint	Dùng để
`GET /chat/zns/templates?account_id=cha_…`	Mẫu đã duyệt của một OA, kèm hạn mức hôm nay
`GET /chat/zns/templates/{id}?account_id=cha_…`	Một mẫu kèm danh sách tham số
`POST /chat/zns`	Gửi ngay một tin theo mẫu
`POST /chat/zns/bulk`	Xếp hàng một mẫu cho mọi khách khớp bộ lọc
`GET /chat/zns`	Tin doanh nghiệp đã gửi (lọc theo `customer_id`, `order_id`, `limit`)

Đọc cần scope crm:read, gửi cần crm:write. Key có chat:read / chat:write cũng được chấp nhận. account_id là id của OA đã kết nối: phần cha_… ở cuối địa chỉ trang của OA trong dashboard (…/chat/channels/zalo/cha_…).

Gửi một tin

Các trường trong body:

Trường	Bắt buộc	Ghi chú
`account_id`	Có	Tài khoản Zalo OA (`cha_…`)
`template_id`	Có	Id của mẫu đã duyệt
`phone`	Có	Số di động Việt Nam; `0912 345 678`, `84912345678` và `+84 912 345 678` đều được
`template_data`	Có	Tham số của mẫu, dạng chuỗi (khoá tối đa 60 ký tự, giá trị tối đa 500)
`customer_id`, `order_id`	Không	Gắn tin với khách hàng và đơn hàng
`tracking_id`	Không	Mã tham chiếu của bạn, tối đa 60 ký tự; mặc định là id tin của Hạ Tầng

cURL
Node.js
Python
PHP

curl -X POST https://api.hatang.dev/chat/zns \
  -H "Authorization: Bearer ht_123..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "cha_123",
    "template_id": "231234",
    "phone": "0912345678",
    "template_data": { "customer_name": "Lan", "order_code": "DH1024", "amount": "350.000đ" },
    "order_id": "ord_123"
  }'

import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY);

const { data, error } = await hatang.chat.zns.send({
  account_id: "cha_123",
  template_id: "231234",
  phone: "0912345678",
  template_data: { customer_name: "Lan", order_code: "DH1024", amount: "350.000đ" },
  order_id: "ord_123",
});
if (error) throw new Error(error.message);
if (data.status === "failed") console.error("Zalo từ chối:", data.error);

import os, requests

res = requests.post(
    "https://api.hatang.dev/chat/zns",
    headers={"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"},
    json={
        "account_id": "cha_123",
        "template_id": "231234",
        "phone": "0912345678",
        "template_data": {"customer_name": "Lan", "order_code": "DH1024", "amount": "350.000đ"},
        "order_id": "ord_123",
    },
)
message = res.json()
if message.get("status") == "failed":
    print("Zalo từ chối:", message["error"])

<?php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.hatang.dev']);
$res = $client->post('/chat/zns', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => [
        'account_id' => 'cha_123',
        'template_id' => '231234',
        'phone' => '0912345678',
        'template_data' => ['customer_name' => 'Lan', 'order_code' => 'DH1024', 'amount' => '350.000đ'],
        'order_id' => 'ord_123',
    ],
]);
$message = json_decode($res->getBody(), true);

Response (201 Created):

{
  "object": "chat_zns_message",
  "id": "zns_...",
  "account_id": "cha_123",
  "customer_id": null,
  "order_id": "ord_123",
  "phone": "84912345678",
  "template_id": "231234",
  "template_name": null,
  "template_data": { "customer_name": "Lan", "order_code": "DH1024", "amount": "350.000đ" },
  "tracking_id": null,
  "msg_id": "f1d2...",
  "status": "sent",
  "error": null,
  "created_at": "2026-10-23T03:00:00.000Z"
}

ghi chú

Lời gọi trả về 201 cả khi Zalo từ chối tin. Hãy kiểm tra status: sent nghĩa là Zalo đã nhận (msg_id là mã của Zalo); failed nghĩa là Zalo từ chối, và error chứa mã lỗi, thông báo của Zalo.

Gửi cho nhiều khách

POST /chat/zns/bulk nhận account_id, template_id, mapping (gán mỗi tham số của mẫu với customer.name, customer.phone, customer.email, field:<key> hoặc text:<văn bản cố định>), filters không bắt buộc (q, stage, owner_id, label, channel) và limit (1 đến 5.000, mặc định 1.000). Response là 202 Accepted:

{ "object": "chat_zns_bulk", "queued": 418, "skipped": 12 }

skipped đếm những khách không có số điện thoại hoặc có số không phải số di động Việt Nam hợp lệ.

Sự kiện webhook

Mỗi lần gửi phát sự kiện chat.zns.sent hoặc chat.zns.failed kèm đối tượng tin như trên. Xem Webhook.

Giới hạn và lưu ý

Số điện thoại được chuẩn hoá về dạng 84…. Số nào sau khi chuẩn hoá không có 11 hoặc 12 chữ số bị từ chối với 422 validation_error.
Chỉ gửi được mẫu đã duyệt. Mẫu không ở trạng thái bật sẽ không có trong danh sách.
Hạn mức hằng ngày thuộc về OA và do Zalo đặt. Trang Zalo ZNS và GET /chat/zns/templates cho biết hạn mức còn lại.
account_id phải là một Zalo OA. Tài khoản Zalo cá nhân không gửi được ZNS.

Xử lý sự cố

Bạn thấy	Nguyên nhân	Cách xử lý
"Không tải được mẫu: … ZNS cần OA ở gói trả phí và có mẫu đã duyệt."	OA đang ở gói miễn phí, hoặc kết nối đã hết hạn	Nâng gói OA, hoặc kết nối lại ở Hỗ trợ → Kênh
"Chưa có mẫu nào được duyệt"	Chưa có mẫu nào được Zalo duyệt	Tạo mẫu tại oa.zalo.me → ZNS → Mẫu và chờ duyệt
"Hãy kết nối Zalo Official Account … trước"	Chưa có Zalo OA nào đang hoạt động	Kết nối OA, hoặc kết nối lại nếu OA cần cấp quyền lại
Tin có trạng thái `failed`	Zalo từ chối: sai tham số, hết hạn mức, hoặc số điện thoại không dùng Zalo	Đọc `error`, sửa dữ liệu mẫu hoặc chờ hạn mức được đặt lại
Tin gửi hàng loạt cứ nằm trong hàng đợi	Module Khách hàng đang tắt	Bật lại module

Bước tiếp theo

Zalo OA: kết nối Official Account dùng để gửi ZNS.
Tự động hoá: tự gửi ZNS khi đơn được thanh toán.
Webhook: theo dõi chat.zns.sent và chat.zns.failed.

Xem trang này dạng Markdown

Trước khi bắt đầu​

Trang Zalo ZNS​

Gửi thông báo cho một đơn hàng​

Gửi cho danh sách khách hàng​

Gửi từ chu trình​

Gửi qua API​

Gửi một tin​

Gửi cho nhiều khách​

Sự kiện webhook​

Giới hạn và lưu ý​

Xử lý sự cố​

Bước tiếp theo​