Cập nhật Template ZBS
API này cho phép bạn chỉnh sửa nội dung của một Template Zalo Business Solution (ZBS) đã khởi tạo, trước khi (hoặc sau khi bị từ chối) xuất bản lên Zalo.
Body của request dùng đúng cấu trúc như API Khởi tạo Template ZBS — bao gồm cả các trường bắt buộc. Đây là thao tác ghi đè: các trường bạn không gửi lên sẽ bị xóa khỏi template, vì vậy hãy gửi lại toàn bộ nội dung template sau khi chỉnh sửa.
Endpoint
PATCH https://staging.manage-api.miniap.vn/api/external/zns-template/<template_id>
PATCH https://manage-api.miniap.vn/api/external/zns-template/<template_id>
PATCH https://manage-api.miniap.vn/api/external/zns-template/68c8ee675f8f83fc813e7830
template_id là _id nhận được khi khởi tạo template (chuỗi ObjectId 24 ký tự hex).
Điều kiện cập nhật
Chỉ template ở trạng thái nháp (DRAFT) hoặc bị từ chối (REJECTED) mới được chỉnh sửa.
| Trạng thái hiện tại | Có thể cập nhật? |
|---|---|
DRAFT | ✅ Được |
REJECTED | ✅ Được — sửa theo góp ý của Zalo rồi xuất bản lại |
PENDING_REVIEW | ❌ Đang chờ Zalo duyệt |
ENABLE | ❌ Đã được duyệt và đang sử dụng |
DISABLE | ❌ Đã bị vô hiệu hóa |
Với template ở trạng thái ENABLE, bạn cần tạo một template mới thay vì chỉnh sửa. Zalo yêu cầu mọi thay đổi nội dung đều phải qua vòng kiểm duyệt lại.
Tham số (Request Body)
Toàn bộ trường và quy tắc giống API Khởi tạo Template ZBS:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
oaId | string | ✅ | ID của Zalo OA dùng để gửi tin. |
name | string | ✅ | Tên template. |
description | string | ❌ | Mô tả ngắn. |
title | string | ✅ | Tiêu đề hiển thị trong tin nhắn. |
tag | "1" | "2" | "3" | ✅ | Cấp độ nội dung (Giao dịch / Chăm sóc khách hàng / Hậu mãi). |
templateType | custom | voucher | rating | ✅ | Loại mẫu tin. |
imageType | logo | image | ✅ | Dùng logo hay ảnh banner. |
logoLight, logoDark | string | ❌ | Logo nền sáng / nền tối (bắt buộc khi imageType = logo). |
images | string[] | ❌ | Danh sách ảnh (bắt buộc ít nhất 1 khi imageType = image). |
contentBlocks | object[] | ✅ | Nội dung tin nhắn (paragraph, table, voucher, rating). |
buttons | object[] | ✅ | Danh sách nút bấm, tối đa 3. |
params | object[] | ✅ | Tham số động kèm techSetting, maxLength, sampleValue. |
voucher / rating | object | ⚠️ | Bắt buộc khi templateType tương ứng. |
isCustomParams | boolean | ✅ | Tự khai báo tham số trong params hay dùng bộ mặc định. |
note | string | ❌ | Ghi chú cho đội kiểm duyệt của Zalo. |
Chi tiết ý nghĩa của tag, techSetting, rowType và type của nút bấm, xem tại Khởi tạo Template ZBS.
API này không đổi trạng thái template — template vẫn giữ nguyên DRAFT / REJECTED. Để đưa lên Zalo kiểm duyệt, gọi API Xuất bản Template ZBS.
Ví dụ Request Body
- Request
{
"oaId": "2288954399991473926",
"name": "Xác nhận đơn hàng (bản cập nhật)",
"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": "Đơn hàng của bạn đã được xác nhận và đang được chuẩn bị."
},
{
"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": "Theo dõi đơ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": "Đang chuẩn bị"
}
],
"note": "Cập nhật nội dung theo góp ý kiểm duyệt"
}
Phản hồi (Response)
- Thành công
- Lỗi 404
- Lỗi 403
{
"template": {
"name": "Xác nhận đơn hàng (bản cập nhật)",
"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": "Đơn hàng của bạn đã được xác nhận và đang được chuẩn bị."
},
{
"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": "Theo dõi đơ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": "Đang chuẩn bị"
}
],
"logoDark": "https://cdn.miniap.vn/zns/logo-dark.png",
"logoLight": "https://cdn.miniap.vn/zns/logo-light.png",
"images": [],
"note": "Cập nhật nội dung theo góp ý kiểm duyệt",
"status": "DRAFT",
"isSync": false,
"isCustomParams": true,
"_id": "68c8ee675f8f83fc813e7830",
"createdAt": "2025-09-16T04:58:15.668Z",
"updatedAt": "2025-09-18T09:12:04.221Z",
"id": "68c8ee675f8f83fc813e7830"
}
}
{
"message": "Không tìm thấy mẫu tin nhắn ZNS"
}
{
"message": "Chỉ có thể cập nhật mẫu tin nhắn ZNS ở trạng thái nháp hoặc bị từ chối"
}
Các trường trong phản hồi phản ánh template sau khi đã cập nhật. Để đưa bản chỉnh sửa lên Zalo kiểm duyệt, gọi API Xuất bản Template ZBS.