API Tạo Template
Template cần được khởi tạo và kiểm duyệt bởi đội ngũ Zalo trước khi có thể sử dụng để gửi tin đến người dùng Zalo.
Doanh nghiệp muốn gửi tin qua SĐT, cần tạo template theo một trong hai phương thức: API tạo template hoặc công cụ tạo template trên ZBS Account (Chi tiết xem tại đây). API tạo template phù hợp với các Agency hoặc doanh nghiệp có nhu cầu gửi tin đa dạng, cần khởi tạo số lượng template lớn và tích hợp vào các hệ thống của doanh nghiệp.
Sau khi gửi request tạo template thành công, đội ngũ Zalo sẽ kiểm duyệt. Sau khi kiểm duyệt xong, một event webhook thay đổi trạng thái template sẽ được gửi về webhook URL đã được thiết lập trước đó của doanh nghiệp. Trạng thái của template sẽ thay đổi từ PENDING_REVIEW sang REJECT nếu bị Zalo từ chối hoặc chuyển sang ENABLE nếu được duyệt.
API này đang được đánh giá lại và có thể có điều chỉnh trong thời gian sắp tới.
→ Khuyến nghị: Ưu tiên tạo và chỉnh sửa Template qua giao diện ZBS Account.
Quyền cần có: Quản lý Message Template
Prequisite
- Mã truy cập (Access Token) được doanh nghiệp (OA) ủy quyền cho App. Lưu ý: Template khởi tạo sẽ thuộc sở hữu của OA.
- Quyền cần có để sử dụng API: Quản lý tài sản.
Giới hạn
- Daily quota của API tạo template: 100 requests/ngày
- Các mẫu tin được phép khởi tạo bao gồm:
- Template Xác thực
- Template Tùy chỉnh
- Template yêu cầu thanh toán
- Template voucher
- Template đánh giá dịch vụ
Mỗi loại mẫu tin sẽ có các quy định cần phải tuân theo khác nhau về các trường thông tin.
HTTP request
- URL: https://business.openapi.zalo.me/template/create
- Method: POST
- Content Type: application/json
- Response Type: application/json
Example request
curl --location 'https://business.openapi.zalo.me/template/create' \
--header 'Content-Type: application/json' \
--header 'access_token: your_access_token' \
--data '{
"template_name": "mẫu chăm sóc khách hàng",
"template_type": "1",
"tag": "1",
"layout": {
"header": {
"components": [
{
"IMAGES": {
"items": [
{
"type": "IMAGE",
"media_id": "1ashjkdbkj"
},
{
"type": "IMAGE",
"media_id": "1ashjkdbkj"
}
]
}
},
{
"LOGO": {
"light": {
"type": "IMAGE",
"media_id": "1ashjkdbkj"
},
"dark": {
"type": "IMAGE",
"media_id": "1ashjkdbkj"
}
}
}
]
},
"body": {
"components": [
{
"TITLE": {
"value": "Xác nhận đơn hàng"
}
},
{
"PARAGRAPH": {
"value": "Cảm ơn <name> đã mua hàng tại cửa hàng. Đơn hàng của bạn đã được xác nhận với chi tiết như sau:"
}
},
{
"OTP": {
"value": "<otp>"
}
},
{
"TABLE": {
"rows": [
{
"value": "<order_code>",
"title": "Mã đơn",
"row_type": 1
},
{
"value": "<phone_number>",
"title": "Điện thoại"
},
{
"value": "<price>",
"title": "Giá tiền"
},
{
"value": "<status>",
"title": "Trạng thái"
},
{
"value": "<date>",
"title": "Ngày đặt hàng"
}
]
}
},
{
"VOUCHER": {
"name": "Giảm 70.000đ",
"condition": "Cho đơn hàng trên 200K",
"voucher_code": "<voucher_code>",
"start_date": "<start_date>",
"end_date": "<end_date>"
}
},
{
"PAYMENT": {
"bank_code": "970416",
"account_name": "CÔNG TY OA NAME",
"account_number": "0123456789",
"amount": "1000000",
"note": "sample note"
}
}
]
},
"footer": {
"components": [
{
"BUTTONS": {
"items": [
{
"content": "https://zalo.solutions/",
"type": 1,
"title": "Xem đơn hàng đã đặt"
}
]
}
}
]
}
},
"params": [
{
"type": "1",
"name": "name",
"sample_value": "nguyen van A"
},
{
"type": "11",
"name": "order_code",
"sample_value": "ABC123"
},
{
"type": "15",
"name": "phone_number",
"sample_value": "0123456789"
},
{
"type": "18",
"name": "price",
"sample_value": "100000"
},
{
"type": "14",
"name": "status",
"sample_value": "DONE"
},
{
"type": "19",
"name": "date",
"sample_value": "19/01/1999"
}
],
"note": "ghi chú kiểm duyệt",
"tracking_id": "abc123"
}'
Tham số header
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
| access_token | string | yes | Đoạn mã cần truyền vào để xác minh quyền sử dụng API. Xem thêm tài liệu tham khảo |
Tham số body của request
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
template_name | string | yes |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
template_type | integer | yes |
Danh sách template_type
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tag | string | yes |
Note: Để tạo được template tag 3, OA cần có quyền gửi template tag 3. Chi tiết cơ chế quyền gửi template tag 3, xem thêm tại đây
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
layout | JSON Array | yes |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
params | JSON Array | No |
Danh sách param type
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
note | string | no |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tracking_id | string | yes |
|
response
{
"error": 0,
"message": "Success",
"data": {
"template_id": "31239",
"template_name": "Xác nhận giao dịch",
"template_type": 1,
"status": "PENDING_REVIEW",
"tag": 1,
"app_id": "21391239109232390",
"oa_id": "19319231302193091",
"price_sdt": "200",
"price_uid": "140",
"price": "200",
"timeout": 7200000,
"preview_url": "https://account.zalo.solutions/znspreview/c1t6Wk43sxXTiLPyC__hXQ=="
}
}
Cấu trúc thuộc tính data
| Thuộc tính | Kiểu dữ liệu | Mô tả |
|---|---|---|
template_id | string | Template ID |
template_name | string | Tên của template |
template_type | string | Loại template. Bao gồm 1 trong các giá trị:
|
status | string | Trạng thái của template sau khi submit: PENDING_REVIEW |
tag | string | Template tag. Bao gồm 1 trong các giá trị:
|
app_id | string | App ID của template |
oa_id | string | OA ID của template |
price_sdt | string | Đơn giá gửi tin qua SĐT. |
price_uid | string | Đơn giá gửi tin qua UID. |
price | string | [DEPRECATED] Đơn giá gửi tin qua SĐT. Trường price đã được thay thế bằng price_sdt và price_uid. Trường này sẽ bị loại bỏ trong các bản cập nhật tiếp theo. |
timeout | long | Timeout của template |
preview_url | string | Link preview template |