--- sourceType: official-guide sourceTypeMatchedRule: fallback slug: OA/tin-nhan/tin-tu-van/gui-tin-tu-van-dinh-kem-anh title: Gửi tin Tư vấn đính kèm ảnh --- # Gửi tin Tư vấn đính kèm ảnh ## HTTP request - **URL:** https://openapi.zalo.me/v3.0/oa/message/cs - **Method:** POST - **Content Type:** application/json - **Response Type:** text/json {/* ![](/assets/OA/img/hinhanh1-1-169x300.png) */} ![](/assets/OA/img/hinhanh1-1-169x300.png) ## Example request ```bash curl \ -X POST \ -H 'Content-Type: application/json' \ -H 'access_token: ' \ -d '{ "recipient": { "user_id": "2468458835296117922" }, "message": { "text": "Zalo đạt 100 triệu người dùng", "attachment": { "type": "template", "payload": { "template_type": "media", "elements": [{ "media_type": "image", "url": "https://stc-developers.zdn.vn/images/bg_1.jpg" }] } } } }' "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](/docs/OA/bat-dau/xac-thuc-va-uy-quyen-cho-ung-dung-new) | 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](/docs/OA/bat-dau/xac-thuc-va-uy-quyen-cho-ung-dung-new). | ### 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ả | | --- | --- | --- | --- | | text | string | no | Tiêu đề của ảnh Giới hạn tối đa là 2.000 ký 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` = 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ố | Loại | Tính bắt buộc | Mô tả | | --- | --- | --- | --- | | template_type | string | yes | Loại template Với template gửi thông báo theo mẫu đính kèm ảnh, giá trị nhận vào là: - `template_type` = media | | elements | array | yes | Các đối tượng của template. Lưu ý: Cấu trúc element thay đổi tùy theo loại template. Với template media, danh sách element bao gồm tối đa 1 phần tử. | ### Cấu trúc thuộc tính message.attachment.payload.element | Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả | | --- | --- | --- | --- | | media_type | string | yes | Loại media. Các giá trị nhận vào: - image: ảnh tĩnh - gif: ảnh động | | attachment_id | string | yes | 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 Lưu ý: - chỉ sử dụng 1 trong 2 biến `attachment_id` hoặc `url` - kích thước ảnh tối ưu 16:9 và vùng safe zone 14:9 | | url | string | yes | Đường dẫn đến ảnh Các định dạng ảnh hỗ trợ: jpg và png Dung lượng tối đa: 1MB Lưu ý: - chỉ sử dụng 1 trong 2 biến `attachment_id` hoặc `url` - kích thước ảnh tối ưu 16:9 và vùng safe zone 14:9 | | width | integer | Chỉ bắt buộc khi `media_type` = gif | Chiều rộng của ảnh | | height | integer | Chỉ bắt buộc khi `media_type` = gif | Chiều cao của ảnh | ## Example respond #### 1. Tin gửi ra là tin trong khung 48h ```json { "data": { "quota": { "quota_type": "reply", "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) ```json { "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 ```json { "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ẻ ```json { "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 ```json { "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í ```json { "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). |