---
title: "Gửi tệp qua trợ lý"
locale: vi
url: https://tlg.builera.app/docs/agent-playbooks/send-file
verified: 2026-10-25
app_version: "2.1"
---

# Gửi tệp qua trợ lý

Đưa ảnh, video hay tài liệu cho Telegram-Auto bằng đường tải lên có hạn hoặc một liên kết HTTPS công khai, kiểm tra tệp rồi mới gửi.


## Mục tiêu

Bạn đưa một tệp vào Telegram-Auto để một tài khoản gửi đi, đăng story, đặt ảnh đại diện hoặc dùng trong bước "gửi tệp" của chiến dịch. Ứng dụng tự kiểm tra tệp (kích thước thật, loại tệp theo byte đầu, SHA-256) trước khi cho dùng.

## Quyền cần

- `messages.send` cho cả bốn thao tác tệp và cho việc gửi.
- Tài khoản dùng tệp phải nằm trong phạm vi kết nối.
- Với chiến dịch: quyền sửa chiến dịch đó.

## Hỏi người trước khi

Hỏi người muốn gửi tệp nào, cho ai, từ tài khoản nào. Không tải lên tệp người chưa đưa cho bạn, và không lấy tệp từ máy hay thư mục riêng của người khác.

## Kiểm trước

Gọi `whoami`. Chọn `purpose` đúng việc:

| `purpose` | Dùng cho | Tối đa |
|---|---|---|
| `message` | `messages.send_media`, `messages.send_album` | 50 MB |
| `story` | `stories.post` | 50 MB |
| `photo` | ảnh đại diện tài khoản / nhóm / bot (`*.set_photo`) | 10 MB |
| `campaign` | bước "gửi tệp" của chiến dịch (cần `campaignId`, không cần `accountId`) | 50 MB |

Mỗi kết nối giữ tối đa 20 tệp đang chờ tải và 50 tệp sẵn sàng chưa dùng.

## Các bước

Có hai cách đưa byte vào. Cả hai kết thúc ở cùng một bước kiểm.

**Cách A — tải lên trực tiếp** (bạn có byte của tệp):

1. Gọi `files.create_upload` với `purpose`, `accountId` (hoặc `campaignId`), `fileName`, `mime`, `size`.
2. Gửi `PUT` nguyên byte tới `uploadUrl`, kèm đúng `headers` trong câu trả lời, trước `completeBefore` (2 giờ).
3. Gọi `files.complete_upload` với `uploadId`. Gọi lại an toàn nếu mạng chập chờn.

**Cách B — liên kết công khai** (tệp đã có trên mạng):

1. Gọi `files.import_url` với `url` HTTPS công khai (cổng 443, không có tên/mật khẩu trong liên kết, không chuyển hướng, tải xong trong 20 giây). Ứng dụng ChatGPT có thể truyền thẳng tham số tệp `file: { download_url, file_name, mime_type }`.

Sau đó:

4. Khi trạng thái là `ready`, lấy `storagePath`. Có thể xem lại bằng `files.status`.
5. Đặt `storagePath` vào thao tác cần dùng, ví dụ `messages.send_media` (kèm `Idempotency-Key`).
6. Theo dõi việc gửi bằng `operations_get`.

> [!IMPORTANT]
> Điểm dừng — hỏi người
>
> Gửi tệp là gửi tin thật cho người thật. Trước khi gọi thao tác gửi, nhắc lại tệp, người nhận và tài khoản gửi để người xác nhận.

## Kiểm sau

Một tệp dùng **một lần**: sau khi gửi, trạng thái thành `used` và không gửi lại được bằng cùng `storagePath`. Muốn gửi lại, tải tệp lên lần nữa. Tệp sẵn sàng mà không dùng sẽ bị xoá sau 24 giờ.

## Khi lỗi

| Mã | Ý nghĩa | Làm gì |
|---|---|---|
| `upload_missing` | Gọi hoàn tất khi chưa `PUT` byte | `PUT` lại rồi gọi hoàn tất |
| `file_mismatch`, `file_type_mismatch` | Byte thật khác loại đã khai | Khai đúng loại, hoặc đổi tệp |
| `file_type_not_allowed` | Loại tệp không hợp với `purpose` (ví dụ SVG làm ảnh đại diện) | Chọn tệp khác |
| `file_too_large` | Vượt giới hạn của `purpose` | Nén hoặc chọn tệp nhỏ hơn |
| `file_not_found` | `storagePath` không phải tệp của kết nối này | Chỉ dùng đường dẫn ứng dụng trả về |
| `file_not_ready` | Tệp đã dùng, hết hạn hay chưa kiểm xong | Tải lên lại |
| `url_blocked`, `url_redirect` | Liên kết trỏ vào mạng nội bộ hoặc chuyển hướng | Dùng liên kết công khai trực tiếp |

Không đổi đuôi tệp để lách bước kiểm.

## Điều kiện dừng

Dừng khi tệp đã gửi xong, khi tệp bị từ chối mà người chưa đưa tệp khác, hoặc khi người chưa xác nhận việc gửi.