Gửi ZNS thông qua API
Tổng quan
-
Để có thể thực hiện gửi ZNS API, cần có Access Token (Mã định danh để gửi ZNS). ZNS cung cấp 2 phương thức để lấy Access token gồm công cụ API explorer hoặc giao thức OAuth
-
Các Template để gửi ZNS cần được khởi tạo trước khi sử dụng. Chi tiết các bước tạo Template có thể xem chi tiết tại đây
Các bước gửi ZNS API
Để thực hiện gửi ZNS API và quản lý trạng thái thông tin ZNS, thực hiện các bước sau:
(1) Gửi ZNS API
Để thực hiện gửi ZNS thông qua API, request cần bao gồm các thông tin sau:
Tham số | Mô tả |
---|---|
access_token | Cần có đoạn mã để xác thực quyền truy cập API. Xem thêm tại đây để biết chi tiết. |
phone | Số điện thoại của người dùng mà Doanh nghiệp muốn gửi ZNS tới. Lưu ý: Số điện thoại phải liên kết với tài khoản Zalo và được viết dưới dạng chuẩn hóa theo mã quốc gia. (Ví dụ: Số điện thoại 0987654321 viết theo định dạng chuẩn tiếng Việt là 84987654321) |
template_id | ID của template muốn sử dụng. |
template_data | Các thuộc tính của template mà đối tác đã đăng ký với Zalo. Lưu ý: Cấu trúc template_data được quy định riêng ứng với từng template. |
tracking_id (không bắt buộc) | Mã số đánh dấu lần gọi API của đối tác, do Doanh nghiệp định nghĩa. Doanh nghiệp có thể dùng tracking_id để đối soát mà không phụ thuộc vào message_id của Zalo cung cấp. |
Example request
curl
-X POST
-H "Content-Type: application/json" -d '{
"phone": "84987654321",
"template_id": "7895417a7d3f9461cd2e",
"template_data": {
"ky": "1",
"thang": "4/2020",
"start_date": "20/03/2020",
"end_date": "20/04/2020",
"customer": "Nguyễn Thị Hoàng Anh",
"cid": "PE010299485",
"address": "VNG Campus, TP.HCM",
"amount": "100",
"total": "100000",
},
"tracking_id":"tracking_id"
}' "https://business.openapi.zalo.me/message/template"
(2) Response
Sau khi yêu cầu được gửi đi, máy chủ Zalo sẽ 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 ngược lại, xem Error Code chi tiết tại đây |
message | Mô tả của lỗi tương ứng |
msg_id | ID của tin ZNS Lưu ý: chỉ trả về nếu yêu cầu thành công |
sent_time | Thời gian máy chủ Zalo bắt đầu gửi ZNS (Định dạng timestamp) |
quota | Thông tin quota của OA Lưu ý: chỉ trả về nếu yêu cầu thành công |
Example response
{
"error": 0,
"message": "Success",
"data": {
"msg_id": "a4d0243feee163bd3af2"
"sent_time": "1626926349402",
"quota": {
"dailyQuota": "500",
"remainingQuota": "499"
}
}
}
Xem chi tiết hơn về cấu trúc của request và response tại đây
(3) Sự kiện gửi ZNS
Nếu request thành công, tin ZNS 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 ZNS.
- delivery_time: Thời gian người dùng nhận được ZNS trên thiết bị.
(4) Sự kiện người dùng nhận được tin ZNS
Nếu ZNS được gửi thành công trên thiết bị của người dùng, thì một sự kiện sẽ được gửi tới URL webhook của Doanh nghiệp.
Tham số | Mô tả |
---|---|
sender | ID của Official Account gửi thông báo |
recipient | Số điện thoại người dùng nhận thông báo |
event_name | Tên sự kiện: user_received_message |
delivery_time | Thời gian trên thiết bị người dùng nhận được ZNS |
msg_id | ID của tin ZNS Lưu ý: chỉ trả về nếu yêu cầu thành công |
tracking_id | Mã số đánh dấu lần gọi API của đối tác, do đối tác định nghĩa ở bước (1) |
app_id | ID của ứng dụng gửi tin (ứng dụng mà OA đã cấp quyền) |
timestamp | Thời điểm gửi sự kiện |
Xem thêm chi tiết sự kiện tại đây.