Gửi tin Tư vấn đính kèm file

lưu ý

để gửi thông báo đính kèm file, bạn cần sử dụng API upload file.

HTTP request

• URL: https://openapi.zalo.me/v3.0/oa/message/cs
• Method: POST
• Content Type: application/json
• Response Type: text/json

Example request

curl \
-X POST \
-H "Content-Type: application/json" \
-H 'access_token: <your_access_token>' \
-d '{
  "recipient": {
    "user_id": "2468458835296117922"
  },
  "message": {
    "attachment": {
        "type": "file",
        "payload": {
            "token": "12i8LV3BcmmDS4iLfyoU3qKxHXNtpu077ZjA7xRHmmi8EXrEjuR50LHjJXJWWvTQ17OJ7R2Oc5q4SHSJjPoPKmDq5X2tyS4MI78oKexCna1CUJnQyiMvUKmfG7UOX8PYVW5FJAckbWbi1tWbj8BnCNOyTGMBr8mrG5XZ4epkfbD4HczzjUs3FM0QL1ZM"
        }
    }
  }
}' "https://openapi.zalo.me/v3.0/oa/message/cs"

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ố	Loại	Tính bắt buộc	Mô tả
type	string	yes	Loại attachment Giá trị nhận vào bắt buộc: type = file
payload	object	yes	Chứa payload của attachment muốn gửi. Xem cấu trúc payload tại mục bên dưới.

Cấu trúc thuộc tính message.attachment.payload

Tham số	Loại	Tính bắt buộc	Mô tả
token	string	yes	Chuỗi token được trả về khi sử dụng API upload file.

Example respond

1. Tin gửi ra là tin trong khung 48h

{
  "data": {
    "quota": {
      "remain": "8",
      "total": "8"
    },
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515",
    "sent_time": "1626926349402"
  },
  "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
quota_type	string	Nguồn quota sử dụng Mang giá trị: “reply”
remain	string	Từ ngày 1/1/2026, đối tác có thể gửi tin Tư vấn miễn phí không giới hạn trong khung 48h Lộ trình chuyển đổi như sau: Từ ngày 1/1/2026: luôn trả về giá trị remain = 8 Sau ngày 1/3/2026: sẽ dừng trả về thuộc tính này
total	string	Sau ngày 1/3/2026: sẽ dừng trả về thuộc tính này
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).

2. Tin gửi đến User Quan tâm (khi chưa có tương tác)

{
  "data": {
    "quota": {
      "quota_type": "welcome_msg",
      "remain": "2",
      "total": "3"
    },
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515",
    "sent_time": "1626926349402"
  },
  "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
quota_type	string	Nguồn quota sử dụng Mang giá trị: "welcome_msg"
remain	string	Số lượt gửi tin tin Tư vấn miễn phí
total	string	Tổng số lượt gửi tin tin Tư vấn miễn phí
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).

3. Tin gửi ra là tin nằm trong hạn mức miễn phí theo gói

{
  "data": {
    "quota": {
      "quota_type": "sub_quota",
      "remain": "1990",
      "total": "2000",
      "expired_date": "11/02/2023"
    },
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515",
    "sent_time": "1626926349402"
  },
  "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
quota_type	string	Nguồn quota sử dụng Mang giá trị: “sub_quota”
remain	string	Số lượt gửi tin Tư vấn miễn phí theo gói dịch vụ OA còn lại
total	string	Tổng số lượng gửi tin Tư vấn miễn phí theo gói dịch vụ OA
expired_date	string	Ngày hết hạn sử dụng tin Tư vấn miễn phí theo gói dịch vụ OA
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).

4. 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",
    "sent_time": "1626926349402"
  },
  "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
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
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).

5. 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",
    "sent_time": "1626926349402"
  },
  "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
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
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).

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

{
  "data": {
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515",
    "sent_time": "1626926349402"
  },
  "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
sent_time	string	Thời gian gửi tin UID (định dạng timestamp).