Gửi ZNS Journey

Khi có nhu cầu gửi ZNS theo hành trình cho hành trình giao vận hoặc vé xe khách, bạn có thể sử dụng chuỗi tin ZNS Journey tương ứng với 1 trong 2 hành trình để tối ưu chi phí.

Mô hình ZNS Journey

Một ZNS Journey được định nghĩa là một chuỗi các tin ZNS gửi đến 1 khách hàng, tính phí theo một mô hình riêng (thay vì theo từng tin).
ZNS Journey hiện tại được chia theo 2 industries chính:
- Logistics: Hành trình giao vận
- Coach bus: Hành trình xe khách
Các mẫu tin ZNS trong bộ ZNS Journey cần phải được khai báo trước khi sử dụng.

1. Request Token

Cần phải có Journey Token để thực hiện chuỗi gửi ZNS Journey đến khách hàng. Từng khách hàng, cho từng hành trình, sẽ có từng Journey Token khác nhau.

Mỗi token được sin ra sẽ không bị tính phí liền

Sẽ được tính phí khi gửi tin nhắn đầu tiên với token đó

Đơn giá mỗi token là 180vnđ

Sử dụng API dưới đây để tạo một journey token mới cho một khách hàng

HTTP request

URL: https://apis.infinix.vn/v1/zns/<slug-api-key>/journey/get-token
Method: POST
Content Type: application/json
Response Type: application/json

Example request

curl --location 'https://apis.infinix.vn/v1/zns/vng-oa-key-0a65/joủney/get-token
--header 'api-key: 6829c1b8a87b979819a760d908fa8a0' \
--header 'Content-Type: application/json' \
--data '{
    "phone": "0943961910",
    "tokenType": "token_logistics_7"
}'

Tham số header

Tham số

Kiểu dữ liệu

Tính bắt buộc

Mô tả

api-key

string

yes

Đoạn mã cần truyền vào để xác minh quyền sử dụng API

Cấu trúc body request

Tham số

Kiểu dữ liệu

Tính bắt buộc

Mô tả

phone

string

yes

SĐT của người nhận. 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. (VD: SĐT 0987654321 viết theo định dạng chuẩn hóa của Việt Nam là 84987654321 hoặc +84987654321)

tokenType

string

Loại Journey token muốn khởi tạo, bao gồm

token_logistics_7
token_logistics_30
token_coach_bus_7
token_coach_bus_30

PS: Mặc định sẽ là token_logistics_7

⚠️ Lưu ý Journey token gồm 4 loại chính, bao gồm:

Industry

Token type

Journey token

Giao vận

token_logistics_7

Token hành trình giao vận 7 ngày

Giao vận

token_logistics_30

Token hành trình giao vận 30 ngày

Xe khách

token_coach_bus_7

Token hành trình xe khách 7 ngày

Xe khách

token_coach_bus_30

Token hành trình xe khách 30 ngày

Nếu tham số tokenType không được truyền, mặc định tokenType = token_logistics_7.

Example response

{
    "success": true,
    "data": {
        "id": "3fa1b090-8642-4208-90cf-18ad12886246",
        "journeyId": "1398239944527896576",
        "journeyTokenType": "token_logistics_7",
        "phone": "0943961910",
        "expiredAt": "2025-08-01T09:46:20.825Z"
    },
    "meta": {
        "sessionId": "e7202e25-6605-4efe-9856-7c9d8e0b7516"
    }
}

Cấu trúc các thuộc tính response

Tham số

Kiểu dữ liệu

string

ID của Journey trong hệ thống InfiniX

journeyId

string

ID của Journey trong hệ thống Zalo

journeyTokenType

string

Loại Token

phone

string

Số điện thoại người nhận tương ứng với token đó

expiredAt

Date

thời gian token sẽ hết hạn

2. Gửi ZNS Journey

HTTP request

URL: https://apis.infinix.vn/v1/zns/<slug-api-key>/send-message-template
Method: POST
Content Type: application/json
Response Type: application/json

Example request

curl --location 'https://apis.infinix.vn/v1/zns/vng-oa-key-0a65/send-message-template'
--header 'api-key: 6829c1b8a87b979819a760d908fa8a0' \
--header 'Content-Type: application/json' \
--data '{
    "type": "JOURNEY",
    "journeyId": "1398242429423448064",
    "phone": "0943961910",
    "templateId": "363328",
    "templateData": {
        "order_code": "order_code_sample",
        "sender_name": "sender_name_sample",
        "order_status": "order_status_sample",
        "pickup_address": "pickup_address_sample",
        "order_description": "order_description_sample",
        "sender_phone_number": "sender_phone_number_sample"
    },
    "mode": "development",
    "sync": false,
    "trackingId": "c365f3bc-2994-4314-91d4-a3719f049bf8"
}'

Tham số header

Tham số

Kiểu dữ liệu

Tính bắt buộc

Mô tả

api-key

string

yes

Đoạn mã cần truyền vào để xác minh quyền sử dụng API

Cấu trúc body request

Tham số

Kiểu dữ liệu

Tính bắt buộc

Mô tả

type

string

yes

Truyền type là JOURNEY

journeyId

string

yes

JourneyID của Zalo được trả về ở API Request Token ứng với số điện thoại người nhận

phone

string

yes

templateId

string

yes

ID của template muốn sử dụng. templateId sẽ được phía Zalo cung cấp riêng cho từng đối tác.

templateData

JSON Object

yes

Các thuộc tính của template mà đối tác đã đăng ký với Zalo. Lưu ý: Cấu trúc templateData được quy định riêng ứng với từng template.

trackingId

string

ID tuỳ chỉnh từ phía đối tác để theo dõi tin nhắn. Nếu như đối tác không truyền trackingId, hệ thống InfiniX sẽ tự sinh ra một trackingId Lưu ý: Chỉ hỗ trợ UUID hoặc MongoDB ObjectId

mode

enum string - development - production

Chỉ định ZNS được gửi ở cơ chế nào. Gồm 2 mode: - development - production Lưu ý: mode "development" chỉ gửi được tới quản trị viên của ứng dụng hoặc quản trị viên của OA. Chỉ dùng để test trong quá trình tích hợp, không thể gửi đến khách hàng

sync

boolean

Sử dụng api ở cơ chế đồng bộ hoặc bất đồng bộ - True: Đồng bộ - sẽ chờ đợi để trả về kết quả của request ZNS qua Zalo - False: Bất đồng bộ - sẽ trả về ngay requestId và sử dụng api Get Result để lấy kết quả request ZNS

Example response

{
    "success": true,
    "data": {
        "phone": "84962938734",
        "type": "JOURNEY",
        "createdAt": "2024-10-07T09:13:10.351Z",
        "status": "PENDING",
        "trackingId": "13d1d775-3f65-4149-91a7-f6e4fd805ee7"
    },
    "meta": {
        "sessionId": "e7202e25-6605-4efe-9856-7c9d8e0b7516"
    }
}

Cấu trúc các thuộc tính response

Tham số

Kiểu dữ liệu

phone

string

Số điện thoại người nhận

type

string

Loại tin ZNS được gửi

sessionId

string

Mỗi request sẽ sinh ra 1 sessionId để nhận diện

createdAt

Date

Thời gian khởi tạo request

status

string

Trạng thái của request

trackingId

String

ID định danh được truyền từ phía khách hàng hoặc được sinh ra từ hệ thống InfiniX

PreviousGửi ZNS OTP NextLấy chi tiết 1 tin nhắn ZNS

Last updated 19 days ago