Gửi ZNS Journey qua API

Tổng quan

ZNS Journey là một chuỗi các tin ZNS được gửi đến người dùng Zalo, được áp dụng cơ chế tính phí riêng để tối ưu chi phí cho đối tác trong việc gửi tin ZNS với các use-cases như theo hóa đơn tiền điện nước, hành trình giao vận hoặc mua hàng so với gửi từng tin ZNS riêng lẻ.
Để có thể thực hiện gửi ZNS journey cần phải có Journey token (Journey token như một định danh để gửi ZNS).
Các mẫu (template) để gửi ZNS Journey cần được khởi tạo trước theo luồng riêng (thông qua Bộ phận CSKH tại Zalo Official Account/kênh email)

Gửi ZNS Journey

Để gửi ZNS Journey, cần thực hiện các bước sau:

alt_text

(1) Khởi tạo Journey token

Gửi request đến server Zalo để khởi tạo Journey token, bao gồm các thông tin bắt buộc:

Parameter	Mô tả
access_token	Đoạn mã cần truyền vào để xác minh quyền sử dụng API. Xem thêm tài liệu tham khảo.
phone	Số điện thoại của người nhận.

Example request

curl --location
--request POST 'https://business.openapi.zalo.me/journey/get-token'
--header 'Content-Type: application/json'
--header 'access_token: your_access_token'
--data-raw '{ "phone":"84987654321" }'

(2) Response

Sau khi request, server Zalo phản hồi các thông tin sau:

Parameter	Mô tả
error	error = 0 nếu request thành công và ngược lại. Chi tiết Error code.
message	Mô tả của mã lỗi tương ứng
token	Mã journey token được kích hoạt \n Note: chỉ được trả về nếu request thành công
journey_id	ID của Journey

Example response

{
    "error": 0,
    "message": "Success",
    "token": "8iCeIhJbTcPtLo0Kh1kS6rOVXl0Rgv2wZNPRaW61sKQaXTGth1KrhGwQrDVXHnJbckzcL8fG-k_X0h1IL-SyeBPfCtwyljtiKutpUQvih7P65AgvJiz9fYYSHkrdrVNuCdPAMeVCYgERu3UWmQOjKMfLWsII_u5E9ylCO46Z-_mFSJC7DstAkBxFVcJTlzduNMsQzxBVaUom9E_06p1cw7DKRtGjLAF0jkfKgj0ftMI=",
    "journey_id": "123456789"
}

* Lưu ý: journey_token chỉ tồn tại trong 7 ngày từ thời điểm được kích hoạt Xem thêm cấu trúc của request và response tại đây

(3) Gửi ZNS với Journey token

Sử dụng Journey token được phản hồi ở bước (2) để gửi ZNS. Cần truyền vào các thông tin bắt buộc sau:

Parameter	Mô tả
access_token	Đoạn mã cần truyền vào để xác minh quyền sử dụng API
journey_token	Đoạn mã xác minh ZNS Journey vừa được kích hoạt
phone	Số điện thoại của người nhận mẫu tin Lưu ý: SĐT phải được liên kết với tài khoản Zalo và được viết ở định dạng chuẩn hóa theo mã quốc gia.
template_id	ID của template ZNS muốn sử dụng. Đối với ZNS được gửi bằng Journey token, cần sử dụng mẫu template riêng mà Zalo cung cấp.
template_data	Các thuộc tính của template mà đối tác đã đăng ký với Zalo

Example request

curl --location
--request POST 'https://business.openapi.zalo.me/message/template'
--header 'Content-Type: application/json'
--header 'access_token: your_access_token'
--header 'journey_token: 8iCeIhJbTcPtLo0Kh1kS6rOVXl0Rgv2wZNPRaW61sKQaXTGth1KrhGwQrDVXHnJbckzcL8fG-k_X0h1IL-SyeBPfCtwyljtiKutpUQvih7P65AgvJiz9fYYSHkrdrVNuCdPAMeVCYgERu3UWmQOjKMfLWsII_u5E9ylCO46Z-_mFSJC7DstAkBxFVcJTlzduNMsQzxBVaUom9E_06p1cw7DKRtGjLAF0jkfKgj0ftMI='
--data-raw
'{
    "template_data": {
    },
    "phone": "84987654321",
   "template_id":217489
}'

(4) Response

Sau khi request gửi ZNS với journey token ở bước (3), tùy theo trạng thái của tin gửi sẽ nhận lại phản hồi tương ứng từ server Zalo.

Parameter	Mô tả
error	error = 0 nếu request thành công và ngược lại. Chi tiết Error code.
message	Mô tả của mã lỗi tương ứng
msg_id	ID của thông báo ZNS. Note: only available if the request is successful
sent_time	Thời gian Zalo server gửi thông báo ZNS (Định dạng timestamp)
remainingQuota	Số lượng tin ZNS có thể gửi còn lại trong 1 ngày. Note: chỉ được trả về nếu request thành công
dailyQuota	Số lượng tin ZNS có thể gửi trong 1 ngày. Note: chỉ được trả về nếu request thành công

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "sent_time": "1640144305350",
        "quota": {
            "remainingQuota": "480",
            "dailyQuota": "500"
        },
        "msg_id": "6e84304c259208ce5181"
    }
}

(5) ZNS được gửi đến thiết bị người nhận

Chi tiết các thiết lập và các example request: Xem tại tài liệu tham khảo.

Kiểm tra Journey Token

Để có thể kiểm tra thông tin của Journey Token, sử dụng API như sau

(1) Request

Parameter	Mô tả
access_token	Đoạn mã cần truyền vào để xác minh quyền sử dụng API
journey_token	Đoạn mã xác minh ZNS Journey vừa được kích hoạt

Example request

curl --location --request GET 'https://business.openapi.zalo.me/journey/check-token' \
--header 'Content-Type: application/json' \
--header 'access_token: access_token' \
--header 'journey_token: journey_token'

(2) Response

Sau khi request với access_token và journey_token, Zalo sẽ trả về response tương ứng với các trường thông tin

Parameter	Mô tả
created_at	Thời gian tạo Journey Token (Định dạng Timestamp)
expired_at	Thời gian Journey Token hết hạn sử dụng (Định dạng Timestamp)
app_id	ID của ứng dụng
oa_id	ID của OA

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "appId": "4349311699477619340",
        "oaId": "3886651700907664415",
        "createdAt": "1641269204370",
        "expiredAt": "1641269384370"
    }
}

Xem chi tiết response tại đây

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

Tổng quan​