Chuyển tới nội dung chính

Khởi tạo Template ZBS

API này cho phép bạn khởi tạo một Template Zalo Business Solution (ZBS) với đầy đủ nội dung hiển thị và các tham số động.

Luồng sử dụng:

  1. Khởi tạo template bằng API này — template được lưu ở trạng thái DRAFT và phản hồi trả về _id.
  2. Xuất bản template bằng API Xuất bản Template ZBS để gửi lên Zalo kiểm duyệt (PENDING_REVIEW).
  3. Sau khi Zalo duyệt (ENABLE), template mới có thể dùng để gửi tin nhắn.
Nội dung template được mô tả bằng contentBlocks

Từ phiên bản mới, nội dung hiển thị của template được khai báo qua mảng contentBlocks (đoạn văn, bảng, voucher, đánh giá) thay cho hai trường paragraphs và tables trước đây.

Endpoint​

🔗Endpoint Staging
Endpoint
POST https://staging-manage.api.miniai.vn/api/external/zns-template/create
🔗Endpoint Production
Endpoint
POST https://manage-api.miniap.vn/api/external/zns-template/create

Tham số (Request Body)​

Thông tin chung​

TrườngKiểuBắt buộcMô tả
oaIdstring✅ID của Zalo OA dùng để gửi tin. Bắt buộc phải có trước khi xuất bản template.
namestring✅Tên template (dùng để quản lý nội bộ).
descriptionstring❌Mô tả ngắn về mục đích template.
titlestring✅Tiêu đề hiển thị trong tin nhắn. Có thể chèn tham số động dạng <customer_fullname>.
tag"1" | "2" | "3"✅Cấp độ (loại nội dung) của template — xem bảng Cấp độ template.
templateTypecustom | voucher | rating✅Loại mẫu tin — xem Loại template.
imageTypelogo | image✅Kiểu ảnh đầu tin: dùng logo hay dùng ảnh banner.
logoLightstring❌URL logo cho nền sáng. Bắt buộc khi imageType = logo (kiểm tra lúc xuất bản).
logoDarkstring❌URL logo cho nền tối. Bắt buộc khi imageType = logo.
imagesstring[]❌Danh sách URL ảnh. Bắt buộc ít nhất 1 ảnh khi imageType = image.
contentBlocksobject[]✅Nội dung thân tin nhắn — xem contentBlocks.
buttonsobject[]✅Danh sách nút bấm, tối đa 3 nút — xem buttons.
paramsobject[]✅Khai báo tham số động — xem params.
voucherobject⚠️Bắt buộc khi templateType = voucher — xem Mẫu voucher.
ratingobject⚠️Bắt buộc khi templateType = rating — xem Mẫu đánh giá.
isCustomParamsboolean✅true nếu bạn tự khai báo tham số trong params; false nếu dùng bộ tham số mặc định của hệ thống.
notestring❌Ghi chú gửi kèm cho đội kiểm duyệt của Zalo (giải thích ngữ cảnh sử dụng mẫu tin).
Không cần gửi status

Template luôn được tạo ở trạng thái DRAFT, kể cả khi bạn gửi kèm status. Việc chuyển trạng thái được thực hiện qua API Xuất bản Template ZBS.

Cấp độ template (tag)​

Zalo phân loại mẫu tin theo cấp độ nội dung; cấp độ ảnh hưởng đến chính sách kiểm duyệt và giá gửi tin.

tagCấp độNội dung phù hợp
"1"Giao dịchXác thực tài khoản, OTP, xác nhận đơn hàng/giao dịch, biến động số dư…
"2"Chăm sóc khách hàngTích lũy điểm thành viên, cập nhật chính sách, khảo sát ý kiến, chúc mừng sinh nhật…
"3"Hậu mãiGiới thiệu sản phẩm/dịch vụ mới, mã giảm giá và CTKM, mời gia hạn dịch vụ…

Loại template (templateType)​

Giá trịTênMô tả
customTin tùy chỉnhMẫu tin tự do: thông báo giao dịch, OTP, nhắc nhở…
voucherMẫu voucherGửi mã giảm giá / voucher kèm điều kiện và hạn sử dụng.
ratingMẫu đánh giáThu thập đánh giá của khách sau khi dùng sản phẩm/dịch vụ.

Nội dung tin nhắn (contentBlocks)​

contentBlocks là mảng các khối nội dung, hiển thị theo đúng thứ tự bạn khai báo.

TrườngKiểuBắt buộcMô tả
idstring✅Định danh duy nhất của khối (UUID do bạn sinh ra).
typeparagraph | table | voucher | rating✅Loại khối nội dung.
valuestring⚠️Nội dung văn bản — dùng cho khối paragraph. Có thể chèn tham số <order_code>.
rowsobject[]⚠️Các dòng của bảng — dùng cho khối table.
voucherobject⚠️Thông tin voucher — dùng cho khối voucher.
ratingobject⚠️Thông tin đánh giá — dùng cho khối rating.

Dòng bảng (rows)​

TrườngKiểuBắt buộcMô tả
labelstring✅Nhãn hiển thị bên trái (ví dụ Mã đơn hàng).
keystring✅Giá trị hiển thị bên phải; dùng <ten_tham_so> để chèn tham số động.
rowTypenumber❌Hiệu ứng màu của dòng, mặc định 0.

Giá trị rowType:

rowTypeÝ nghĩa
0Không có hiệu ứng
1Thành công (xanh lá)
2Cập nhật (xanh dương)
3Lưu ý (vàng)
4Báo lỗi (đỏ)
5Cơ bản

Tham số động (params)​

Mỗi tham số bạn dùng trong title, paragraph hay rows đều phải được khai báo trong params.

TrườngKiểuBắt buộcMô tả
keystring✅Tên tham số, không kèm dấu <> (ví dụ order_code).
labelstring✅Tên hiển thị của tham số trong trình soạn thảo.
techSettingstring✅Loại kỹ thuật do Zalo quy định — quyết định cách kiểm duyệt và độ dài tối đa.
maxLengthnumber✅Độ dài tối đa của giá trị truyền vào, theo đúng techSetting.
sampleValuestring✅Giá trị mẫu dùng để Zalo xem trước và kiểm duyệt.
rowTypenumber❌Hiệu ứng màu áp dụng cho tham số, mặc định 0.
isFixedboolean❌true nếu giá trị cố định, không truyền động khi gửi tin.

Bảng techSetting và maxLength tương ứng:

techSettingLoại dữ liệumaxLength
"1"Tên khách hàng30
"2"Số điện thoại15
"3"Địa chỉ200
"4"Mã số (mã đơn hàng, mã khách hàng…)30
"5"Nhãn tùy chỉnh30
"6"Trạng thái giao dịch30
"7"Thông tin liên hệ50
"8"Giới tính / Danh xưng5
"9"Tên sản phẩm / Thương hiệu200
"10"Số lượng / Số tiền20
"11"Thời gian20
"12"OTP10
"13"URL200
"14"Tiền tệ (VNĐ)12
"15"Nội dung chuyển khoản90
Chọn đúng techSetting

Tham số thiếu techSetting sẽ khiến request xuất bản template trả về lỗi 400. Chọn sai loại kỹ thuật (ví dụ dùng Nhãn tùy chỉnh cho số tiền) là nguyên nhân phổ biến khiến Zalo từ chối duyệt mẫu tin.

Nút bấm (buttons)​

Tối đa 3 nút cho mỗi template.

TrườngKiểuBắt buộcMô tả
labelstring✅Nhãn hiển thị trên nút.
typestring✅Loại hành động của nút — xem bảng dưới.
valuestring✅Giá trị đích của hành động (URL, số điện thoại, ID Mini App…). Có thể để chuỗi rỗng với các loại không cần giá trị.
typeHành động
"1"Đến trang của doanh nghiệp
"2"Gọi điện (giá trị là số điện thoại)
"3"Đến trang thông tin OA
"4"Đến Zalo Mini App của doanh nghiệp
"5"Đến trang ứng dụng của doanh nghiệp
"6"Đến trang phân phối sản phẩm
"7"Đến trang web / Zalo Mini App khác
"8"Đến ứng dụng khác
"9"Đến bài viết của doanh nghiệp
"10"Đến trang đích kêu gọi tải ứng dụng

Mẫu voucher​

Khi templateType = voucher, trường voucher ở cấp cao nhất là bắt buộc:

TrườngKiểuMô tả
codestringMã voucher (thường là một tham số động, ví dụ <voucher_code>).
titlestringTên chương trình / ưu đãi.
conditionstringĐiều kiện áp dụng.
startDatestringNgày bắt đầu hiệu lực.
expiryDatestringNgày hết hạn.
Nội dung hiển thị nằm trong contentBlocks

Trường voucher (và rating) ở cấp cao nhất dùng để kiểm tra dữ liệu đầu vào. Nội dung thực sự được hiển thị trong tin nhắn là khối voucher / rating bên trong contentBlocks, nên hãy khai báo trùng khớp ở cả hai nơi.

Mẫu đánh giá​

Khi templateType = rating, trường rating ở cấp cao nhất là bắt buộc và chứa mảng items (ít nhất 1 phần tử):

TrườngKiểuMô tả
starnumberSố sao tương ứng với kịch bản trả lời (1–5).
titlestringTiêu đề hiển thị cho mức sao đó.
questionstringCâu hỏi tiếp theo dành cho khách.
answersstring[]Danh sách đáp án gợi ý.
thanksstringLời cảm ơn sau khi khách đánh giá.
descriptionstringMô tả bổ sung.

Ví dụ Request Body​

{
    "oaId": "2288954399991473926",
    "name": "Xác nhận đơn hàng",
    "description": "Thông báo xác nhận đơn hàng cho khách",
    "title": "Xin chào <customer_fullname>,",
    "tag": "1",
    "templateType": "custom",
    "imageType": "logo",
    "logoLight": "https://cdn.miniap.vn/zns/logo-light.png",
    "logoDark": "https://cdn.miniap.vn/zns/logo-dark.png",
    "images": [],
    "isCustomParams": true,
    "contentBlocks": [
        {
            "id": "10c8db12-7f66-4b53-a79c-22b5a01dac49",
            "type": "paragraph",
            "value": "Cảm ơn bạn đã đặt hàng tại cửa hàng. Đơn hàng của bạn đã được xác nhận."
        },
        {
            "id": "6f2b0a54-1f5a-4f0f-9a52-0f5b2b6c7d10",
            "type": "table",
            "rows": [
                { "label": "Mã đơn hàng", "key": "<order_code>", "rowType": 0 },
                { "label": "Trạng thái", "key": "<order_status>", "rowType": 1 },
                { "label": "Tổng thanh toán", "key": "<order_price>", "rowType": 0 }
            ]
        }
    ],
    "buttons": [
        {
            "label": "Xem đơn hàng",
            "value": "https://manage.miniai.vn/orders",
            "type": "1"
        }
    ],
    "params": [
        {
            "key": "customer_fullname",
            "label": "Customer fullname",
            "techSetting": "1",
            "maxLength": 30,
            "sampleValue": "Nguyễn Văn A"
        },
        {
            "key": "order_code",
            "label": "Order code",
            "techSetting": "4",
            "maxLength": 30,
            "sampleValue": "DH123456"
        },
        {
            "key": "order_status",
            "label": "Order status",
            "techSetting": "6",
            "maxLength": 30,
            "sampleValue": "Đã xác nhận"
        },
        {
            "key": "order_price",
            "label": "Order price",
            "techSetting": "14",
            "maxLength": 12,
            "sampleValue": "1500000"
        }
    ],
    "note": "Mẫu tin gửi khi đơn hàng được xác nhận"
}

Phản hồi (Response)​

{
    "template": {
        "name": "Xác nhận đơn hàng",
        "description": "Thông báo xác nhận đơn hàng cho khách",
        "oaId": "2288954399991473926",
        "tag": "1",
        "templateType": "custom",
        "imageType": "logo",
        "title": "Xin chào <customer_fullname>,",
        "contentBlocks": [
            {
                "id": "10c8db12-7f66-4b53-a79c-22b5a01dac49",
                "type": "paragraph",
                "value": "Cảm ơn bạn đã đặt hàng tại cửa hàng. Đơn hàng của bạn đã được xác nhận."
            },
            {
                "id": "6f2b0a54-1f5a-4f0f-9a52-0f5b2b6c7d10",
                "type": "table",
                "rows": [
                    { "label": "Mã đơn hàng", "key": "<order_code>", "rowType": 0 },
                    { "label": "Trạng thái", "key": "<order_status>", "rowType": 1 },
                    { "label": "Tổng thanh toán", "key": "<order_price>", "rowType": 0 }
                ]
            }
        ],
        "buttons": [
            {
                "label": "Xem đơn hàng",
                "value": "https://manage.miniai.vn/orders",
                "type": "1"
            }
        ],
        "params": [
            {
                "key": "customer_fullname",
                "label": "Customer fullname",
                "techSetting": "1",
                "maxLength": 30,
                "sampleValue": "Nguyễn Văn A"
            },
            {
                "key": "order_code",
                "label": "Order code",
                "techSetting": "4",
                "maxLength": 30,
                "sampleValue": "DH123456"
            },
            {
                "key": "order_status",
                "label": "Order status",
                "techSetting": "6",
                "maxLength": 30,
                "sampleValue": "Đã xác nhận"
            },
            {
                "key": "order_price",
                "label": "Order price",
                "techSetting": "14",
                "maxLength": 12,
                "sampleValue": "1500000"
            }
        ],
        "logoDark": "https://cdn.miniap.vn/zns/logo-dark.png",
        "logoLight": "https://cdn.miniap.vn/zns/logo-light.png",
        "images": [],
        "note": "Mẫu tin gửi khi đơn hàng được xác nhận",
        "shopId": "64204a17a5a97a86f12e1f0a",
        "status": "DRAFT",
        "isSync": false,
        "isCustomParams": true,
        "_id": "68c8ee675f8f83fc813e7830",
        "createdAt": "2025-09-16T04:58:15.668Z",
        "updatedAt": "2025-09-16T04:58:15.668Z",
        "id": "68c8ee675f8f83fc813e7830"
    }
}
Bước tiếp theo

Dùng _id trong phản hồi làm template_id để gọi API Xuất bản Template ZBS, sau đó tra cứu lại bằng Lấy chi tiết template.