Nhảy tới nội dung
Sản phẩm ZNS

Tài liệu hướng dẫn

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:

alt_text

(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_tokenCầ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.
phoneSố đ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_idID của template muốn sử dụng.
template_dataCá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ả
error0 nếu request thành công
ngược lại, xem Error Code chi tiết tại đây
messageMô tả của lỗi tương ứng
msg_idID của tin ZNS
Lưu ý: chỉ trả về nếu yêu cầu thành công
sent_timeThời gian máy chủ Zalo bắt đầu gửi ZNS (Định dạng timestamp)
quotaThô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ả
senderID của Official Account gửi thông báo
recipientSố điện thoại người dùng nhận thông báo
event_nameTên sự kiện: user_received_message
delivery_timeThời gian trên thiết bị người dùng nhận được ZNS
msg_idID của tin ZNS
Lưu ý: chỉ trả về nếu yêu cầu thành công
tracking_idMã 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_idID của ứng dụng gửi tin (ứng dụng mà OA đã cấp quyền)
timestampThời điểm gửi sự kiện

Xem thêm chi tiết sự kiện tại đây.