Gửi tin qua API
Quý khách có 2 cách gửi Tin nhắn ZBS Template: gửi qua API hoặc gửi theo chiến dịch (không cần API). Bài này hướng dẫn luồng gửi tin qua API, từ lấy Access Token đến nhận sự kiện khi người dùng nhận được tin.
Chọn cách gửi tin phù hợp
| Tiêu chí | Gửi qua API | Gửi theo chiến dịch (không qua API) |
|---|---|---|
| Cách gửi | Gửi qua API | Gửi qua file Excel tải lên tài khoản ZBS |
| Yêu cầu | Cần nhân lực có kiến thức về kỹ thuật | Cần chuẩn bị file Excel |
| Số lượng | Gửi số lượng lớn | Gửi số lượng có hạn mức |
| Dữ liệu gửi | Không được lưu trên tài khoản ZBS | Được lưu trên tài khoản ZBS |
Không có đội kỹ thuật? Quý khách xem Gửi tin theo chiến dịch (không cần API).
Luồng gửi tin qua API

Luồng API giữa đối tác gửi tin, máy chủ Zalo và người nhận tin.
Bước 1 · Lấy Access Token
Access Token là mã định danh để Ứng dụng (AppID) gửi tin thay mặt OA. Quý khách lấy Access Token theo 1 trong 2 cách:
- Công cụ API Explorer: dành cho Admin của OA hoặc Ứng dụng. Xem hướng dẫn tại Uỷ quyền Ứng dụng (AppID) cho OA.
- Giao thức OAuth: dành cho người có kiến thức lập trình, hoặc khi doanh nghiệp dùng Ứng dụng của bên thứ 3. Xem tại Xác thực và uỷ quyền cho Ứng dụng.
Lưu ý: Access Token có hiệu lực 25 giờ. Khi hết hạn, Quý khách dùng Refresh Token (hiệu lực 3 tháng) để tạo lại Access Token mới.
Bước 2 · Gửi request API
Gửi request POST đến https://business.openapi.zalo.me/message/template, kèm access_token ở header và các thông tin sau ở body:
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
phone | Có | Số điện thoại người nhận, đã liên kết với tài khoản Zalo, viết theo mã quốc gia. Ví dụ: 0987654321 viết thành 84987654321 |
template_id | Có | ID của mẫu tin đã được duyệt |
template_data | Có | Dữ liệu truyền vào các tham số của mẫu |
tracking_id | Có | Mã do doanh nghiệp tự đặt để đối soát từng lần gửi, nên dài tối đa 48 ký tự và không chứa ký tự đặc biệt |
Cấu trúc request đầy đủ xem tại API Gửi tin trên Zalo for Developers.
Bước 3 · Nhận phản hồi (response)
Sau khi request được gửi đi, máy chủ Zalo phản hồi với các thông tin sau:
| Tham số | Mô tả |
|---|---|
error | 0 nếu request thành công. Mã khác 0 là mã lỗi, xem cách xử lý tại Xử lý mã lỗi |
message | Mô tả của lỗi tương ứng |
msg_id | ID của tin. Chỉ trả về nếu request thành công |
sent_time | Thời gian máy chủ Zalo bắt đầu gửi tin (định dạng timestamp) |
quota | Thông tin hạn mức gửi tin của OA: dailyQuota là số tin được gửi trong ngày, remainingQuota là số tin còn lại trong ngày. Chỉ trả về nếu request thành công |
Ví dụ response:
{
"error": 0,
"message": "Success",
"data": {
"msg_id": "a4d0243feee163bd3af2",
"sent_time": "1626926349402",
"quota": {
"dailyQuota": "500",
"remainingQuota": "499"
}
}
}
Bước 4 · Theo dõi sự kiện gửi tin
Nếu request thành công, tin sẽ được gửi tới người dùng:
sent_time: thời điểm máy chủ Zalo bắt đầu gửi tin.delivery_time: thời điểm người dùng nhận được tin trên thiết bị.
Bước 5 · Nhận sự kiện người dùng nhận được tin
Khi tin đến thiết bị của người dùng, hệ thống gửi sự kiện user_received_message tới Webhook URL của Ứng dụng với các thông tin:
| Tham số | Mô tả |
|---|---|
sender.id | ID của Official Account gửi tin |
recipient.id | Số điện thoại người dùng nhận tin |
event_name | Tên sự kiện: user_received_message |
message.delivery_time | Thời gian thiết bị của người dùng nhận được tin |
message.msg_id | ID của tin |
message.tracking_id | Mã đánh dấu lần gọi API, do doanh nghiệp tự đặt ở bước gửi request |
app_id | ID của Ứng dụng gửi tin (Ứng dụng đã được OA cấp quyền) |
timestamp | Thời điểm gửi sự kiện |
Lưu ý: Thời điểm người dùng nhận tin là giá trị của
delivery_time, không phải thời điểm webhook nhận sự kiện hay giá trịtimestamp.
Chi tiết sự kiện xem tại Sự kiện người dùng nhận tin qua SĐT.
Câu hỏi thường gặp
Gửi tin bị báo lỗi thì xử lý thế nào?
Quý khách xem giá trị error trong response và tra cách xử lý tại Xử lý mã lỗi.
Chi phí gửi tin qua API tính thế nào?
Chi phí tuỳ loại mẫu và thành phần trong mẫu. Với tin gửi qua số điện thoại, chỉ tính phí khi tin đến thiết bị người nhận trong thời gian timeout quy định; với tin gửi qua UID, tin được tính phí khi server Zalo xử lý thành công. Quý khách xem tại Cơ chế tính giá tin nhắn.
Bài viết liên quan
- Uỷ quyền Ứng dụng (AppID) cho OA
- Gửi tin theo chiến dịch (không cần API)
- Xử lý mã lỗi
- Định dạng dữ liệu cho tham số
Cần hỗ trợ thêm?
Gửi yêu cầu qua Mẫu hỗ trợ Zalo Business Solutions. Đội ngũ chăm sóc khách hàng sẽ phản hồi trong vòng 24 giờ làm việc.