Gửi tin Truyền thông cá nhân
Từ 01/01/2026, giải pháp tin nhắn với mẫu tin (template) được ra mắt gọi là ZBS Template Message. Dịch vụ Tin UID Giao dịch (165 vnd) và UID Truyền thông cá nhân sẽ được dừng cung cấp từ 01/03/2026. Xem chi tiết tại đây.
HTTP request
- URL: https://openapi.zalo.me/v3.0/oa/message/promotion
- Method: POST
- Content Type: application/json
- Response Type: application/json
Example request
curl --location 'https://openapi.zalo.me/v3.0/oa/message/promotion'
--header 'access_token: <your_oa_access_token>'
--header 'Content-Type: application/json'
--data '{
"recipient": {
"user_id": "4356639876691778517"
},
"message": {
"attachment": {
"type": "template",
"payload": {
"template_type": "promotion",
"elements": [
{
"attachment_id":"aERC3A0iYGgQxim8fYIK6fxzsXkaFfq7ZFRB3RCyZH6RyziRis3RNydebK3iSPCJX_cJ3k1nW1EQufjN_pUL1f6Ypq3rTef5nxp6H_HnXKFDiyD5y762HS-baqRpQe5FdA376lTfq1sRyPr8ypd74ecbaLyA-tGmuJ-97W",
"type": "banner"
},
{
"type": "header",
"content": "💥💥Ưu đãi thành viên Platinum💥💥"
},
{
"type": "text",
"align": "left",
"content": "Ưu đãi dành riêng cho khách hàng Nguyen Van A hạng thẻ Platinum<br>Voucher trị giá 150$"
},
{
"type": "table",
"content": [
{
"value": "VC09279222",
"key": "Voucher"
},
{
"value": "30/12/2023",
"key": "Hạn sử dụng"
}
]
},
{
"type": "text",
"align": "center",
"content": "Áp dụng tất cả cửa hàng trên toàn quốc"
}
],
"buttons": [
{
"title": "Tham khảo chương trình",
"image_icon": "",
"type": "oa.open.url",
"payload": {
"url": "https://oa.zalo.me/home"
}
},
{
"title": "Liên hệ chăm sóc viên",
"image_icon": "aeqg9SYn3nIUYYeWohGI1fYRF3V9f0GHceig8Ckq4WQVcpmWb-9SL8JLPt-6gX0QbTCfSuQv40UEst1imAm53CwFPsQ1jq9MsOnlQe6rIrZOYcrlWBTAKy_UQsV9vnfGozCuOvFfIbN5rcXddFKM4sSYVM0D50I9eWy3",
"type": "oa.query.hide",
"payload": "#tuvan"
}
]
}
}
}
}
}
'
Tham số header
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
| access_token | string | yes | Token cho phép ứng dụng đại diện OA gọi API. Xem chi tiết cách lấy access token tại đây. |
Cấu trúc body của request
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
recipient | object | yes | Thông tin người nhận |
message | object | yes | Nội dung cần gửi |
Cấu trúc thuộc tính recipient
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
user_id | string | yes | ID của người nhận (nhận được thông qua API truy xuất chi tiết người dùng, API truy xuất danh sách người dùng) |
Cấu trúc thuộc tính message
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
attachment | object | yes | Attachment cần gửi |
Cấu trúc thuộc tính message.attachment
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
type | string | yes | Loại attachment. Giá trị nhận vào bắt buộc:
|
payload | object | yes | Chứa payload của attachment muốn gửi |
Cấu trúc thuộc tính message.attachment.payload
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
template_type | string | yes | Loạitemplate. Giá trị nhận vào bắt buộc:
|
language | string | no | Ngôn ngữ sử dụng của tin Giá trị nhận vào:
hoặc
Khi chọn ngôn ngữ các nội dung mặc định của mẫu tin sẽ chuyển sang ngôn ngữ tương ứng |
elements | array | yes | Các đối tượng của template. |
buttons | array | no | Các nút nhấn CTA (tùy chọn có hoặc không, tối đa 4 button) Xem thêm mục message.attachment.payload.buttons bên dưới |
Cấu trúc tham số message.attachment.payload.elements
| Type | Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|---|
| banner | image_url | string | yes | image_url : Đường dẫn đến ảnh
|
attachment_id | string | yes | attachment_id: ID của ảnh bạn muốn sử dụng (nhận được thông qua API upload ảnh)
| |
| header | content | string | yes | Nội dung của header, tối đa 100 ký tự. |
align | string | no | Chấp nhận 3 giá trị
| |
text | content | string | yes | Nội dung của text, tối đa 1000 ký tự mỗi đoạn |
align | string | no | Chấp nhận 3 giá trị
| |
table | Content | array | yes | Cấu trúc 1 phần tử trong table bao gồm:
|
Cấu trúc tham số message.attachment.payload.buttons
Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
|---|---|---|---|
title | string | yes | Tiêu đề của button Lưu ý: Tiêu đề không được vượt quá 35 ký tự |
image_icon | string | yes | Có thể tryền:
Lưu ý: Kích thước hình ảnh tối ưu: 100px * 100px |
type, payload | object | yes | Tham khảo các loại action được hỗ trợ tại đây |
Example respond
{
"data": {
"message_id": "e6fa968f027",
"user_id": "4356639876691778517"
},
"error": 0,
"message": "Success"
}
Cấu trúc thuộc tính data
| Thuộc tính | Kiểu dữ liệu | Mô tả |
|---|---|---|
message_id | string | ID của thông báo |
user_id | string | ID của người nhận |