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

Gửi tin giao dịch

🚩Lưu ý:

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​

Example request​

curl --location 'https://openapi.zalo.me/v3.0/oa/message/transaction'
--header 'access_token: <your_oa_access_token>'
--header 'Content-Type: application/json'
--data '{
    "recipient": {
        "user_id": "5373093274852641073"
    },
    "message": {
        "attachment": {
            "type": "template",
            "payload": {
                "template_type": "transaction_order",
                "language": "VI",
                "elements": [
                    {
                        "attachment_id": "a-JJEvLdkcEPxTOwb6gYTfhwm26VSBHjaE3MDfrWedgLyC0smJRiA8w-csdGVg1cdxZLPT1je7k4i8nwbdYrSCJact3NOVGltEUQTjDayIhTvf1zqsR-Ai3aboRERgjvm-cI8iqv-NoIxi0cdNBoE6SYVJooM6xKTBft",
                        "type": "banner"
                    },
                      {
                        "type": "header",
                        "content": "Trạng thái đơn hàng",
                        "align": "left"
                    },
                    {
                        "type": "text",
                        "align": "left",
                        "content": "• Cảm ơn bạn đã mua hàng tại cửa hàng.<br>• Thông tin đơn hàng của bạn như sau:"
                    },
                    {
                        "type": "table",
                        "content": [
                            {
                                "value": "F-01332973223",
                                "key":"Mã khách hàng"
                            },
                            {
                                "style": "yellow",
                                "value": "Đang giao",
                                "key": "Trạng thái"
                            },
                            {
                                "value": "250,000đ",
                                "key": "Giá tiền"
                            }
                        ]
                    },
                    {
                        "type": "text",
                        "align": "center",
                        "content": "📱Lưu ý điện thoại. Xin cảm ơn!"
                    }
                ],
                "buttons": [
                    {
                        "title": "Kiểm tra lộ trình - default icon",
                        "image_icon": "",
                        "type": "oa.open.url",
                        "payload": {
                            "url": "https://oa.zalo.me/home"
                        }
                    },
                    {
                        "title": "Xem lại giỏ hàng",
                        "image_icon": "wZ753VDsR4xWEC89zNTsNkGZr1xsPs19vZF22VHtTbxZ8zG9g24u3FXjZrQvQNH2wMl1MhbwT5_oOvX5_szXLB8tZq--TY0Dhp61JRfsAWglCej8ltmg3xC_rqsWAdjRkctG5lXzAGVlQe9BhZ9mJcSYVIDsc7MoPMnQ",
                        "type": "oa.query.show",
                        "payload": "kiểm tra giỏ hàng"
                    }
                    ,
                    {
                        "title": "Liên hệ tổng đài",
                        "image_icon": "gNf2KPUOTG-ZSqLJaPTl6QTcKqIIXtaEfNP5Kv2NRncWPbDJpC4XIxie20pTYMq5gYv60DsQRHYn9XyVcuzu4_5o21NQbZbCxd087DcJFq7bTmeUq9qwGVie2ahEpZuLg2KDJfJ0Q12c85jAczqtKcSYVGJJ1cZMYtKR",
                        "type": "oa.open.phone",
                        "payload": {
                            "phone_code":"84123456789"
                        }
                    }
                ]
            }
        }
    }
}
'

Tham số header​

Tham sốKiểu dữ liệuTính bắt buộcMô 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ệuTính bắt buộcMô 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ệuTính bắt buộcMô 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ệuTính bắt buộcMô 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ệuTính bắt buộcMô tả

type

string

yes

Loại attachment.

Giá trị nhận vào bắt buộc:

  • type = template

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ệuTính bắt buộcMô tả

template_type

string

yes

Loại template

Các giá trị nhận vào: Xem bảng message.attachment.payload.template_type

Lưu ý: "Loại tin" trong table sẽ hiển thị theo giá trị của template_type

language

string

no

Ngôn ngữ sử dụng của tin

Giá trị nhận vào:

  • language = VI

hoặc

  • language = EN

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.

Xem thêm mục message.attachment.payload.elements bên dưới

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

Tham số message.attachment.payload.template_type​

STTMã templateLoại tin (VN)Message Type (EN)Ngành áp dụng

1

transaction_billing

Hóa đơn

Billing

Tất cả

2

transaction_order

Đơn hàng

Order

Tất cả

3

transaction_reward

Tích điểm

Reward

Tất cả

4

transaction_contract

Hợp đồng

Contract

Tất cả

5

transaction_booking

Lịch hẹn

Booking

Tất cả

6

transaction_membership

Thành viên

Membership

Tất cả

7

transaction_event

Sự kiện

Event

Tất cả

8

transaction_transaction

Giao dịch

Transaction

Tất cả

9

transaction_account

Tài khoản

Account

Tất cả

10

transaction_internal

Nội bộ

Internal

Tất cả

11

transaction_partnership

Đối tác

Partnership

Tất cả

12

transaction_education

Học vụ

Education

Giáo dục và đào tạo

13

transaction_rating

Đánh giá

Rating

Tất cả

Cấu trúc tham số message.attachment.payload.elements​

TypeTham số

Kiểu dữ liệu

Tính bắt buộcMô tả
banner

image_url

string

yes

image_url : Đường dẫn đến ảnh
Các định dạng ảnh hỗ trợ: jpg và png
Dung lượng tối đa: 1MB
Tỉ lệ kích thước ảnh (height :width): từ 1:5 đến 1:1 (ảnh vuông)

Lưu ý: chỉ sử dụng 1 trong 2 biến image_url hoặc attachment_id

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)
Các định dạng ảnh hỗ trợ: jpg và png
Dung lượng tối đa: 1MB
Tỉ lệ kích thước ảnh (height :width): từ 1:5 đến 1:1 (ảnh vuông)

Lưu ý: chỉ sử dụng 1 trong 2 biến image_url hoặc attachment_id

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ị

  • left (hoặc để trống): canh lề bên trái
  • center: canh lề giữa
  • right: canh lề bên phải

text
Lưu ý: tối đa được 2 đoạn text

content

string

yes

Nội dung của text, tối đa 250 ký tự mỗi đoạn

align

string

no

Chấp nhận 3 giá trị

  • left (hoặc để trống): canh lề bên trái
  • center: canh lề giữa
  • right: canh lề bên phải
table

content

array

yes

Cấu trúc 1 phần tử trong table là:
  • {
      "key": "giá trị của key", // maxlength = 35
      "value": "giá trị của value" // maxlength = 100
    }

  • Trong đó bắt buộc phải có 1 trong 2 phần tử dưới đây:



    • VN:

      {
        "key": "Mã...", // bắt đầu là "Mã", dùng định danh người nhận
        "value": "Giá trị tự do"
      }



      EN:

      {
        "key": "...Code...", // bắt buộc có chứa "Code" trong key
        "value": "Giá trị tự do"
      }

      • hoặc

    • VN:

      {
        "key": "Tên khách hàng", // key có giá trị cố định "Tên khách hàng"
        "value": "Giá trị tự do"
      }

      EN:

      {
        "key": "Customer Name", // key có giá trị cố định "Customer Name"
        "value": "Giá trị tự do"
      }

  • Key "Trạng thái" / "Status" là key duy nhất hiện tại được phép sử dụng tham số "Style":

    • VN:

      {
         "key": "Trạng thái" // key có giá trị cố định "Trạng thái"
         "value": "Giá trị tự do"
         "style": "yellow" // Giá trị hợp lệ: green, blue, yellow, red, grey
      }

      EN:

      {
         "key": "Status" // key có giá trị cố định "Status"
         "value": "Giá trị tự do"
         "style": "yellow" // Giá trị hợp lệ: green, blue, yellow, red, grey
      }
    • Các giá trị của "style": green, blue, yellow, red, grey
  • Ngoài các phần tử hệ thống quy định như trên, nhà phát triển có thể khai báo thêm tối đa 5 phần tử tùy ý.

Cấu trúc tham số message.attachment.payload.buttons​

Lưu ý

Hỗ trợ tối đa 4 button

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:

  • image url của hình ảnh
  • attachment_id sau khi sử dụng API upload hình ảnh
  • để trống hoặc “default”: để sử dụng imaeg icon mặc định của Zalo

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

1. Tin gửi ra là tin nằm trong hạn mức gói tính năng lẻ​

{
  "data": {
    "quota": {
      "quota_type": "purchase_quota",
      "owner_type": "OA",
      "owner_id": "4462152339089565647"
    },
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515"
  },
  "error": 0,
  "message": "Success"
}

Cấu trúc thuộc tính data​

Thuộc tínhKiểu dữ liệuMô tả

message_id

string

ID của thông báo

user_id

string

ID của người nhận

quota_type

string

Nguồn quota sử dụng
Mang giá trị: “purchase_quota”

owner_type

string

Thực thể sở hữu Quota Package
Giá trị:
  • OA: Thực thể sở hữu là OA
  • App: Thực thể sở hữu là App

    • owner_id

    string

    ID thực thể sở hữu Quota Package
    Giá trị: OA ID hoặc App ID

    2. Tin gửi ra là tin nằm trong hạn mức Redeem code​

    {
      "data": {
        "quota": {
          "quota_type": "reward_quota",
          "owner_type": "OA",
          "owner_id": "4462152339089565647"
        },
        "message_id": "63ecf43f0df7dba892e6",
        "user_id": "2512523625412515"
      },
      "error": 0,
      "message": "Success"
    }

    Cấu trúc thuộc tính data​

    Thuộc tínhKiểu dữ liệuMô tả

    message_id

    string

    ID của thông báo

    user_id

    string

    ID của người nhận

    quota_type

    string

    Nguồn quota sử dụng
    Mang giá trị: “reward_quota”

    owner_type

    string

    Thực thể sở hữu Quota Package
    Giá trị:
  • OA: Thực thể sở hữu là OA
  • App: Thực thể sở hữu là App

    • owner_id

    string

    ID thực thể sở hữu Quota Package
    Giá trị: OA ID hoặc App ID

    3. Tin gửi ra là tin tính phí​

    {
      "data": {
        "message_id": "63ecf43f0df7dba892e6",
        "user_id": "2512523625412515"
      },
      "error": 0,
      "message": "Success"
    }

    Cấu trúc thuộc tính data​

    Thuộc tínhKiểu dữ liệuMô tả

    message_id

    string

    ID của thông báo

    user_id

    string

    ID của người nhận