Nhảy tới nội dung
Gửi tin qua API

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 APIGửi theo chiến dịch (không qua API)
Cách gửiGửi qua APIGửi qua file Excel tải lên tài khoản ZBS
Yêu cầuCần nhân lực có kiến thức về kỹ thuậtCần chuẩn bị file Excel
Số lượngGửi số lượng lớnGửi số lượng có hạn mức
Dữ liệu gửiKhô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​

Sequence diagram API giữa đối tác gửi tin, máy chủ Zalo và người nhận tin

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:

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ộcMô tả
phoneCó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_idCóID của mẫu tin đã được duyệt
template_dataCóDữ liệu truyền vào các tham số của mẫu
tracking_idCó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ả
error0 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
messageMô tả của lỗi tương ứng
msg_idID của tin. Chỉ trả về nếu request thành công
sent_timeThời gian máy chủ Zalo bắt đầu gửi tin (định dạng timestamp)
quotaThô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.idID của Official Account gửi tin
recipient.idSố điện thoại người dùng nhận tin
event_nameTên sự kiện: user_received_message
message.delivery_timeThời gian thiết bị của người dùng nhận được tin
message.msg_idID của tin
message.tracking_idMã đánh dấu lần gọi API, do doanh nghiệp tự đặt ở bước gửi request
app_idID của Ứng dụng gửi tin (Ứng dụng đã được OA cấp quyền)
timestampThờ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​

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.