OA send file

API

API dùng để gửi tin nhắn đính kèm tệp tin (file) từ Official Account (OA) Zalo đến người dùng, sử dụng token đã nhận được từ API upload-file

POST $BASE_URL/api/vendor/v1/zalo/oa-send-file

Lưu ý

• API-KEY: là duy nhất
• Các bước lấy API-KEY:
  1. Doanh nghiệp đăng nhập
  2. Di chuyển đến trang Key (hoặc License)
  3. Lấy 1 API-KEY thỏa mãn điều kiện hoạt động
• Người dùng phải đã tương tác với Official Account (OA) Zalo thì mới có user_id để dùng vào request (lấy user_id thì cần nhắn yêu cầu tới Zalo OA)

Thông tin Request

• Method: POST

• URL: /api/vendor/v1/zalo/oa-send-file

• Headers:

  • accept: */*
  • Content-Type: application/json
  • API-KEY: {API_KEY}

• Parameters:

  • API-KEY: Key License

• Body:

  • message: (Mô tả dữ liệu message)
  • oa_id: ID của OA
  • recipient: (Mô tả dữ liệu recipient)

• Cấu trúc request

Key	Type Value	Required	Description
API-KEY header	string	true	Key License
oa_id body	string	true	ID của OA
message body	object	true	token với kiểu dữ liệu là string đại diện cho file được gửi đi, lấy từ API upload-file
recipient body	object	true	user_id với kiểu dữ liệu là string, là ID của người nhận tin nhắn trên eTelecom

• Ví dụ Request

curl --location 'https://cpaas.interits.com:8080/api/vendor/v1/zalo/oa-send-file' \
--header 'API-KEY: EImADVLv3tjE0ExErTkhTbKxBWeWwhY' \
--header 'Content-Type: application/json' \
--data '{
  "message": {
    "token": "cY243q77r2kDTPuM2yoDUyy_X1v8riiiq6hLHadLd2pKETH17j3EA88YXXeRpSiWXYcC7HR4n26EBOCV4Q-IOj8OsGiqXf8rqco81XlOkrpxN8Kj0jwW5PDEiseBuA8dsmwEJYAChYw_4uvoUBkXJu49cX14igDoloQN54ZAq2xJ8PXw7ftU4zKYm2bDcuj1tNEISqMUt4lL89ecH9dIIzHoptEetNyBMecFT0"
  },
  "oa_id": "94900466102472689",
  "recipient": {
    "user_id": "3918660744667407780"
  }
}'

Thông tin Response

Mô tả: Mô tả dữ liệu trả về dùng làm gì

• Cấu trúc data của response

Key	Type	Description
direction	string	in out
msg_id	string	ID của thông báo
oa_id	string	ID của OA
recipient_id	string	ID của người nhận
sender_id	string	ID người gửi
shop_id	string	ID của shop trên eTelecom
type	string	unknown text audio video photo GIF file sticker location business_card
user_id	string	ID user trên eTelecom

• Ví dụ Response

{
    "code": 200,
    "data": {
        "direction": "out",
        "msg_id": "4ec5824de520f77bae34",
        "oa_id": "94900466102472689",
        "recipient_id": "3918660744667407780",
        "sender_id": "94900466102472689",
        "shop_id": "1384546016245602051",
        "type": "file",
        "user_id": "0",
        "zl_user_id": "1384546011679036791"
    },
    "referentId": "4ec5824de520f77bae34"
}

Bảng Status Response

Status Code	Status Message	Description
200	OK	Yêu cầu đã thành công và server trả về kết quả.
201	Created	Yêu cầu đã thành công và server đã tạo ra tài nguyên mới.
204	No Content	Yêu cầu đã thành công nhưng không có nội dung trả về.
400	Bad Request	Server không thể hiểu yêu cầu do cú pháp không hợp lệ message: Success: Gửi thành công Unknown error: Xảy ra lỗi không xác định, vui lòng thử lại sau Appllication invalid: Ứng dụng gửi ZNS không hợp lệ Application not existed: Ứng dụng gửi ZNS không tồn tại Application not activated: Ứng dụng chưa được kích hoạt App secret key invalid: Secret key của ứng dụng không hợp lệ Application not link to any OA: Ứng dụng gửi ZNS chưa đươc liên kết với OA nào Method unsupported: Phương thức không được hỗ trợ Message ID invalid: ID thông báo không hợp lệ Phone number invalid: Số điện thoại không hợp lệ Template ID invalid: ID mẫu ZNS không hợp lệ Can not edit this type of template: Template không có trạng thái Reject hoặc Template được tạo từ Admin tool Zalo version unsupported: Phiên bản Zalo app không được hỗ trợ. Người dùng cần cập nhật phiên bản mới nhất Template data empty: Mẫu ZNS không có dữ liệu template data type is not define: Dữ liệu mẫu ZNS không hợp lệ parameter_name data breaks max length: Dữ liệu tham số vượt quá giới hạn ký tự template data is missing a parameter parameter_name: Dữ liệu mẫu ZNS thiếu tham số QR code cannot be generated: Không thể tạo QR code, vui lòng kiểm tra lại parameter_name has invalid format: Dữ liệu tham số không đúng format Button invalid: Button không hợp lệ Invalid button content format: Đường dẫn liên kết không đúng định dạng User is inactive, or reject the message, or using an outdated Zalo version, or other internal errors: Người dùng không nhận được ZNS vì các lý do: Trạng thái tài khoản, Tùy chọn nhận ZNS, Sử dụng Zalo phiên bản cũ, hoặc các lỗi nội bộ khác Out of quota: Tài khoản ZNS không đủ số dư Text invalid: Nội dung tham số không hợp lệ OA or App does not have permission to access this template: OA hoặc ứng dụng gửi ZNS chưa được cấp quyền sử dụng mẫu ZNS này Zalo account not existed: Tài khoản Zalo không tồn tại hoặc đã bị vô hiệu hoá Account can not receive message: Tài khoản không thể nhận ZNS OA does not have permission to use this feature: OA chưa được cấp quyền sử dụng tính năng này OA does not have permission to create this type of template: OA chưa có quyền tạo template tag 3 OA does not have permission to use this resource: OA không có quyền sử dụng media resources (image/logo) Body data empty: Mẫu ZNS không có nội dung Body format invalid: Body request không đúng định dạng JSON RSA message decoded failed: Giải mã nội dung thông báo RSA thất bại Access token invalid: Mã truy cập không hợp lệ Invalid appsecret_proof provided in the API argument: appsecret_proof không hợp lệ Official Account ID invalid: ID Official Account không hợp lệ Out of quota (development mode): Ví (development mode) không đủ số dư Test template messages can only be sent to admin: Template test chỉ có thể được gửi cho quản trị viên Encoding key not existed: Mã encoding key không tồn tại RSA key cannot be generated: Không thể tạo RSA key, vui lòng thử lại sau Maximum character limit exceeded: Nội dung mẫu ZNS vượt quá giới hạn kí tự ZNS template not approved: Mẫu ZNS chưa được phê duyệt Parameter invalid: Tham số không hợp lệ This template cannot be sent at night (10PM-6AM): Mẫu ZNS này không được phép gửi vào ban đêm (từ 22h-6h) User has not responded to opt-in inquiry: Người dùng chưa phản hồi gợi ý nhận ZNS từ OA No permission to send ZNS (not verified, in free subscription plan): OA chưa có quyền gửi ZNS (chưa được xác thực, đang sử dụng gói miễn phí) OA has no permission to send ZNS (The system blocks due to violation detection): OA không có quyền gửi ZNS (Hệ thống chặn do phát hiện vi phạm) ZCA association required: Cần kết nối với ZCA để sử dụng tính năng này ZCA charge failure: Thanh toán ZCA thất bại (ví không đủ số dư, ...) App does not have permission to access this feature: Ứng dụng gửi ZNS chưa có quyền sử dụng tính năng này Extension does not have permission to access ZCA of OA: OA chưa cấp quyền cho Extension về quyền sử dụng ZCA của OA User refused to receive this type of ZNS: Người dùng từ chối nhận loại ZNS này User not eligible to receive this ZNS type based on current delivery policy: Người dùng không đủ điều kiện để nhận loại ZNS này dựa trên chính sách gửi tin hiện tại User refused to receive ZNS: Người dùng từ chối nhận ZNS từ Official Account RSA key not exist: RSA key không tồn tại, vui lòng gọi API tạo RSA key RSA key already existed: RSA key đã tồn tại, vui lòng gọi API lấy RSA key ZNS daily quota exceeded: OA đã vượt giới hạn gửi ZNS trong ngày OA exceeded the monthly promotion quota: OA request gửi vượt ngưỡng monthly promotion quota OA does not have permission to send this type of ZNS: OA không được phép gửi loại nội dung ZNS này Template disabled due to low quality: Mẫu ZNS này đã bị vô hiệu hoá do chất lượng gửi thấp Tempalate daily quota exceeded: Mẫu ZNS đã vượt giới hạn gửi trong ngày OA exceeded the limit of sending ZNS follow-ups to this user for the month.: OA đã vượt giới hạn gửi tin ZNS hậu mãi cho người dùng này trong tháng. ZNS journey token missing: Không tìm thấy ZNS journey token ZNS journey token invalid: ZNS journey token không hợp lệ ZNS journey token type invalid: ZNS journey token type không tương thích với template ZNS journey token expired: ZNS journey token đã hết hạn Not an E2EE template: Không phải mẫu ZNS E2EE Get E2EE key failed: Lấy E2EE key thất bại Data is invalid or detail_reason: Dữ liệu truyền vào sai quy định The uploaded file exceeds the allowed size: Dung lượng file vượt qua dung lượng cho phép The uploaded file does not meet the required format specifications: Định dạng file upload không được cho phép Out of quota: Số lượng tạo/edit template hoặc upload attachment vượt quá daily quota sending_mode has invalid value: sending_mode truyền sai giá trị cho phép Can not send this type of ZNS on this endpoint: Chế độ Gửi vượt hạn mức (sending_mode = 3) không hỗ trợ để gửi tin tag 1, 2
401	Unauthorized	Cần xác thực để truy cập tài nguyên.
403	Forbidden	Server từ chối thực hiện yêu cầu, mặc dù người dùng đã xác thực.
404	Not Found	Tài nguyên yêu cầu không tồn tại trên server.
405	Method Not Allowed	Phương thức HTTP không được phép cho tài nguyên yêu cầu.
500	Internal Server Error	Lỗi không xác định trong server.
502	Bad Gateway	Server là một gateway hoặc proxy và nhận được phản hồi không hợp lệ từ server khác.
503	Service Unavailable	Server không thể xử lý yêu cầu do quá tải hoặc bảo trì.
504	Gateway Timeout	Server không nhận được phản hồi kịp thời từ server phụ trợ.