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

Xác thực (Authentication)

Mọi request phải gửi kèm API key của bạn trong header:

Header	Giá trị	Yêu cầu
x-api-key	miniai-partner <API_KEY_CỦA_BẠN>	Bắt buộc
Content-Type	application/json	Bắt buộc

Không cần gửi shopId

Gian hàng được xác định từ chính API key, nên hệ thống tự gán shopId cho template. Bạn không cần (và không thể) truyền shopId trong request body.

---

Tham số (Request Body)

Thông tin chung

Trường	Kiểu	Bắt buộc	Mô tả
oaId	string	Bắt buộc	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.
name	string	Bắt buộc	Tên template (dùng để quản lý nội bộ).
description	string	Tùy chọn	Mô tả ngắn về mục đích template.
title	string	Bắt buộc	Tiêu đề hiển thị trong tin nhắn. Có thể chèn tham số động dạng <customer_fullname>.
tag	"1" | "2" | "3"	Bắt buộc	Cấp độ (loại nội dung) của template — xem bảng Cấp độ template.
templateType	custom | voucher | rating	Bắt buộc	Loại mẫu tin — xem Loại template.
imageType	logo | image	Bắt buộc	Kiểu ảnh đầu tin: dùng logo hay dùng ảnh banner.
logoLight	string	Tùy chọn	URL logo cho nền sáng. Bắt buộc khi imageType = logo (kiểm tra lúc xuất bản).
logoDark	string	Tùy chọn	URL logo cho nền tối. Bắt buộc khi imageType = logo.
images	string[]	Tùy chọn	Danh sách URL ảnh. Bắt buộc ít nhất 1 ảnh khi imageType = image.
contentBlocks	object[]	Bắt buộc	Nội dung thân tin nhắn — xem contentBlocks.
buttons	object[]	Bắt buộc	Danh sách nút bấm, tối đa 3 nút — xem buttons.
params	object[]	Bắt buộc	Khai báo tham số động — xem params.
voucher	object	Có điều kiện	Bắt buộc khi templateType = voucher — xem Mẫu voucher.
rating	object	Có điều kiện	Bắt buộc khi templateType = rating — xem Mẫu đánh giá.
isCustomParams	boolean	Bắt buộc	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.
note	string	Tùy chọn	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.

tag	Cấp độ	Nội dung phù hợp
"1"	Giao dịch	Xá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àng	Tí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ãi	Giớ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ên	Mô tả
custom	Tin tùy chỉnh	Mẫu tin tự do: thông báo giao dịch, OTP, nhắc nhở…
voucher	Mẫu voucher	Gửi mã giảm giá / voucher kèm điều kiện và hạn sử dụng.
rating	Mẫ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ường	Kiểu	Bắt buộc	Mô tả
id	string	Bắt buộc	Định danh duy nhất của khối (UUID do bạn sinh ra).
type	paragraph | table | voucher | rating	Bắt buộc	Loại khối nội dung.
value	string	Có điều kiện	Nội dung văn bản — dùng cho khối paragraph. Có thể chèn tham số <order_code>.
rows	object[]	Có điều kiện	Các dòng của bảng — dùng cho khối table.
voucher	object	Có điều kiện	Thông tin voucher — dùng cho khối voucher.
rating	object	Có điều kiện	Thông tin đánh giá — dùng cho khối rating.

Dòng bảng (rows)

Trường	Kiểu	Bắt buộc	Mô tả
label	string	Bắt buộc	Nhãn hiển thị bên trái (ví dụ Mã đơn hàng).
key	string	Bắt buộc	Giá trị hiển thị bên phải; dùng <ten_tham_so> để chèn tham số động.
rowType	number	Tùy chọn	Hiệu ứng màu của dòng, mặc định 0.

Giá trị rowType:

rowType	Ý nghĩa
0	Không có hiệu ứng
1	Thành công (xanh lá)
2	Cập nhật (xanh dương)
3	Lưu ý (vàng)
4	Báo lỗi (đỏ)
5	Cơ 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ường	Kiểu	Bắt buộc	Mô tả
key	string	Bắt buộc	Tên tham số, không kèm dấu <> (ví dụ order_code).
label	string	Bắt buộc	Tên hiển thị của tham số trong trình soạn thảo.
techSetting	string	Bắt buộc	Loại kỹ thuật do Zalo quy định — quyết định cách kiểm duyệt và độ dài tối đa.
maxLength	number	Bắt buộc	Độ dài tối đa của giá trị truyền vào, theo đúng techSetting.
sampleValue	string	Bắt buộc	Giá trị mẫu dùng để Zalo xem trước và kiểm duyệt.

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

techSetting	Loại dữ liệu	maxLength
"1"	Tên khách hàng	30
"2"	Số điện thoại	15
"3"	Địa chỉ	200
"4"	Mã số (mã đơn hàng, mã khách hàng…)	30
"5"	Nhãn tùy chỉnh	30
"6"	Trạng thái giao dịch	30
"7"	Thông tin liên hệ	50
"8"	Giới tính / Danh xưng	5
"9"	Tên sản phẩm / Thương hiệu	200
"10"	Số lượng / Số tiền	20
"11"	Thời gian	20
"12"	OTP	10
"13"	URL	200
"14"	Tiền tệ (VNĐ)	12
"15"	Nội dung chuyển khoản	90

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ường	Kiểu	Bắt buộc	Mô tả
label	string	Bắt buộc	Nhãn hiển thị trên nút.
type	string	Bắt buộc	Loại hành động của nút — xem bảng dưới.
value	string	Bắt buộc	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ị.

type	Hà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ường	Kiểu	Mô tả
code	string	Mã voucher (thường là một tham số động, ví dụ <voucher_code>).
title	string	Tên chương trình / ưu đãi.
condition	string	Điều kiện áp dụng.
startDate	string	Ngày bắt đầu hiệu lực.
expiryDate	string	Ngà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 chỉ dùng để kiểm tra dữ liệu đầu vào — hệ thống không lưu lại và không trả về trong phản hồi. 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 và đọc lại giá trị từ contentBlocks.

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ường	Kiểu	Mô tả
star	number	Số sao tương ứng với kịch bản trả lời (1–5).
title	string	Tiêu đề hiển thị cho mức sao đó.
question	string	Câu hỏi tiếp theo dành cho khách.
answers	string[]	Danh sách đáp án gợi ý.
thanks	string	Lời cảm ơn sau khi khách đánh giá.
description	string	Mô tả bổ sung.

---

Ví dụ Request (cURL)

cURL

curl -X POST 'https://manage-api.miniap.vn/api/external/zns-template/create' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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",
    "isCustomParams": true,
    "contentBlocks": [
      {
        "id": "10c8db12-7f66-4b53-a79c-22b5a01dac49",
        "type": "paragraph",
        "value": "Cảm ơn bạn đã đặt 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 }
        ]
      }
    ],
    "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" }
    ]
  }'

Không cần gửi shopId

Hệ thống tự xác định shopId từ API key của bạn nên không cần gửi shopId trong body. Chi tiết đầy đủ từng trường xem ở phần ví dụ bên dưới.

---

Ví dụ Request Body

Tin tùy chỉnh

{
    "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"
}

Mẫu voucher

{
    "oaId": "2288954399991473926",
    "name": "Tặng voucher sinh nhật",
    "title": "Chúc mừng sinh nhật <customer_fullname>!",
    "tag": "3",
    "templateType": "voucher",
    "imageType": "image",
    "images": ["https://cdn.miniap.vn/zns/birthday-banner.png"],
    "isCustomParams": true,
    "contentBlocks": [
        {
            "id": "1c2f9a11-2b34-4d55-9f7a-88b0a1cd0f21",
            "type": "paragraph",
            "value": "Cửa hàng gửi tặng bạn một mã ưu đãi nhân dịp sinh nhật."
        },
        {
            "id": "35b8de07-4c11-4f2a-88de-9a1c2e3b4d55",
            "type": "voucher",
            "voucher": {
                "code": "<voucher_code>",
                "title": "Giảm 20% toàn bộ đơn hàng",
                "condition": "Áp dụng cho đơn từ 300.000đ",
                "startDate": "2025-10-01",
                "expiryDate": "2025-10-31"
            }
        }
    ],
    "voucher": {
        "code": "<voucher_code>",
        "title": "Giảm 20% toàn bộ đơn hàng",
        "condition": "Áp dụng cho đơn từ 300.000đ",
        "startDate": "2025-10-01",
        "expiryDate": "2025-10-31"
    },
    "buttons": [
        { "label": "Mua ngay", "value": "https://manage.miniai.vn/shop", "type": "7" }
    ],
    "params": [
        {
            "key": "customer_fullname",
            "label": "Customer fullname",
            "techSetting": "1",
            "maxLength": 30,
            "sampleValue": "Nguyễn Văn A"
        },
        {
            "key": "voucher_code",
            "label": "Voucher code",
            "techSetting": "4",
            "maxLength": 30,
            "sampleValue": "BDAY20"
        }
    ],
    "note": "Mẫu tin tặng voucher sinh nhật"
}

Mẫu đánh giá

{
    "oaId": "2288954399991473926",
    "name": "Khảo sát sau mua hàng",
    "title": "Xin chào <customer_fullname>,",
    "tag": "2",
    "templateType": "rating",
    "imageType": "logo",
    "logoLight": "https://cdn.miniap.vn/zns/logo-light.png",
    "logoDark": "https://cdn.miniap.vn/zns/logo-dark.png",
    "isCustomParams": true,
    "contentBlocks": [
        {
            "id": "9a0f31bd-7d22-4a6d-8b39-1e0c5f2a7c44",
            "type": "paragraph",
            "value": "Bạn hài lòng với trải nghiệm mua hàng vừa rồi chứ?"
        },
        {
            "id": "b71c4d92-5e88-4b1c-9f30-7c2a6e0d8b13",
            "type": "rating",
            "rating": {
                "items": [
                    {
                        "star": 5,
                        "title": "Rất hài lòng",
                        "question": "Điều gì khiến bạn hài lòng nhất?",
                        "answers": ["Sản phẩm tốt", "Giao hàng nhanh"],
                        "thanks": "Cảm ơn bạn đã đánh giá!",
                        "description": ""
                    }
                ]
            }
        }
    ],
    "rating": {
        "items": [
            {
                "star": 5,
                "title": "Rất hài lòng",
                "question": "Điều gì khiến bạn hài lòng nhất?",
                "answers": ["Sản phẩm tốt", "Giao hàng nhanh"],
                "thanks": "Cảm ơn bạn đã đánh giá!",
                "description": ""
            }
        ]
    },
    "buttons": [],
    "params": [
        {
            "key": "customer_fullname",
            "label": "Customer fullname",
            "techSetting": "1",
            "maxLength": 30,
            "sampleValue": "Nguyễn Văn A"
        }
    ],
    "note": "Mẫu tin khảo sát sau mua hàng"
}

---

Phản hồi (Response)

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"
    }
}

Lỗi 400 - Validation

{
    "error": "Bad request",
    "message": "\"oaId\" is required, \"params[0].techSetting\" is required"
}

Lỗi 401 - Xác thực

Phản hồi là chuỗi văn bản thuần (không phải JSON):

Unauthorized

Lỗi 429 - Quá giới hạn

{
    "error": "Too many requests, limit to 100 requests per minute"
}

Lỗi thường gặp

Mã	Nguyên nhân
400	Thiếu trường bắt buộc, sai kiểu dữ liệu, techSetting không hợp lệ, hoặc buttons quá 3 nút
401	Thiếu header x-api-key, sai tiền tố miniai-partner , hoặc API key không hợp lệ
429	Vượt giới hạn số request (xem mục Giới hạn bên dưới)
500	Lỗi hệ thống

Giới hạn (Rate limit)

100 request / phút

Mỗi gian hàng được gọi tối đa 100 request mỗi phút trên toàn bộ External API. Vượt quá giới hạn sẽ nhận mã 429.

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.