Gửi ZNS

API sử dụng để gửi tin nhắn ZNS đến người dùng Zalo

Khi có nhu cầu gửi thử mẫu ZNS để kiểm tra trước khi gửi chính thức, bạn có thể gọi lệnh ZNS API ở chế độ development (development mode). Lưu ý: Chế độ development chỉ hỗ trợ gửi thử mẫu ZNS đến quản trị viên của ứng dụng hoặc quản trị viên của OA.

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 '{
    "phone": "84962938733",
    "templateId": "375847",
    "templateData": {
        "otp": "843176"
    },
    "trackingId": "13d1d775-3f65-4149-91a7-f6e4fd805ee7",
    "mode": "development",
    "sendingMode": "1",
    "sync": true,
    "fallbackList": [
        {
            "method": "SMS",
            "templateId": "1",
            "templateData": {
                "otp_code": "843176",
                "expire_time": "20"
            }
        }
    ],
    "fallbackSLA": 15
}'

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 [phone] viết theo định dạng chuẩn hóa của Việt Nam là 84987654321 hoặc [phone])
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	no	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	no	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	no	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
sendingMode	enum string - 1 - 3	no	Cơ chế gửi ZNS Promotion ở hai chế độ 1 : Gửi normal 3: Gửi vượt hạn mực Lưu ý: Mặc định sẽ gửi ở cơ chế "1", nếu có nhu cầu gửi vượt hạn mức thì gọi "3"
fallbackList	Array Object	no	Danh sách fallback
fallbackSLA	number	yes if fallbackList	Require khi có sử dụng fallback. Sẽ fallback nếu như người dùng chưa nhận được thông báo sau một khoảng thời gian, tuỳ thuộc vào nhu cầu của khách hàng

• Cấu trúc fallbackList

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
method	enum string - ZNS - SMS	yes	Phương thức fallback tin nhắn
templateId	string	yes	ID của template muốn fallback
templateData	JSON Object	yes	Các thuộc tính của template mà đối tác đã đăng ký với InfiniX. Lưu ý: Cấu trúc templateData được quy định riêng ứng với từng template.

Example response

{
    "success": true,
    "data": {
        "phone": "84962938734",
        "type": "NORMAL",
        "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