Telegram getFile: khôi phục liên kết tải xuống đã hết hạn an toàn

Khi liên kết tải tệp của bot Telegram hết hạn, hãy gọi lại getFile bằng file_id của tệp rồi dùng file_path mới trả về. Telegram bảo đảm liên kết đã chuẩn bị có hiệu lực ít nhất một giờ, không phải vĩnh viễn. Không dùng file_unique_id làm mã tải xuống. Cách khôi phục này áp dụng cho Bot API chính thức; URL tạm thời của tệp đính kèm qua webhook hợp nhất tuân theo một đặc tả khác.

Điểm chính

• Nhận được tin nhắn có tệp không có nghĩa là ứng dụng đã lưu nội dung tệp.
• Giữ mã định danh tệp và ngữ cảnh tin nhắn; coi URL tải xuống là địa chỉ tạm thời.
• Khi liên kết Bot API hết hạn, lấy lại qua getFile thay vì thử mãi URL cũ.
• Không áp dụng thời hạn hay cách làm mới của Telegram cho URL tệp đính kèm UnifyPort.

getFile trả về gì và nên lưu gì?

Tài liệu Telegram Bot API mô tả getFile là phương thức lấy thông tin cơ bản và chuẩn bị tệp để tải xuống. Khi thành công, phương thức trả về đối tượng File. Các mã định danh có mục đích khác nhau:

Giá trị	Mục đích theo tài liệu	Cách dùng đề xuất trong ứng dụng
file_id	Tải xuống hoặc tái sử dụng tệp	Lưu cùng danh tính bot đã nhận để gọi getFile về sau
file_unique_id	Nhận diện tệp qua thời gian và giữa các bot; không dùng để tải hay tái sử dụng	Có thể dùng để liên kết dữ liệu, không thay thế mã tải xuống
file_path	Đường dẫn tải tệp đã được chuẩn bị	Dùng phản hồi mới nhất, không coi đường dẫn cũ là cố định
file_name, mime_type	Siêu dữ liệu tài liệu không bắt buộc do người gửi cung cấp	Lưu từ tin nhắn gốc nếu có và kiểm tra trước khi dùng

Cũng cần giữ mã cuộc trò chuyện và tin nhắn gốc. Danh tính tệp không phải quyền truy cập hội thoại: việc cùng một tệp xuất hiện trong cuộc trò chuyện khác không được tự động cấp quyền truy cập bản sao đã lưu.

Đây là các trường của Bot API, không phải phần mở rộng cho sự kiện UnifyPort. Nếu chưa chọn cách tích hợp, hãy đọc so sánh Bot API webhook và webhook đầu vào hợp nhất trước.

Chẩn đoán lỗi tải tệp Telegram theo từng giai đoạn

Chọn cách khôi phục dựa trên bước thực sự bị lỗi, không dựa vào việc hộp thư vẫn hiển thị ảnh thu nhỏ.

Hiện tượng	Kiểm tra tiếp	Giới hạn khôi phục
getFile thất bại	Thông tin xác thực bot, file_id thực tế, lỗi trả về và kích thước tệp	Sửa yêu cầu hoặc chọn cách tải được hỗ trợ trước khi thử lại
Liên kết từng hoạt động không dùng được nữa	Lấy kết quả getFile mới	Thử địa chỉ mới; không phải mọi lỗi HTTP đều chứng minh liên kết hết hạn
Tải xuống bị quá thời gian	Mạng, thời gian chờ của worker và khả năng truy cập nơi lưu trữ	Giới hạn số lần thử; lấy địa chỉ mới nếu nghi hết hạn
Tải thành công nhưng không phân tích được	Nội dung thực tế và định dạng bộ phân tích hỗ trợ	Làm mới liên kết không sửa nội dung không hợp lệ hoặc không được hỗ trợ
Đã nhận webhook nhưng chưa có tệp do mình lưu	Tác vụ tải đã lưu bền vững và kết quả worker	Nhận sự kiện và lưu tệp là hai cột mốc riêng

Hiện tài liệu API và Bots FAQ nêu giới hạn tải xuống 20 MB cho Bot API do Telegram lưu trữ. Đừng nhầm với giới hạn tải lên hoặc toàn bộ khả năng của ứng dụng Telegram. Tài liệu API cũng mô tả việc tải không chịu giới hạn kích thước này khi vận hành máy chủ Bot API cục bộ. Đó là lựa chọn hạ tầng, không phải tham số giúp endpoint do Telegram lưu trữ chấp nhận tệp lớn hơn.

“Ít nhất một giờ” là bảo đảm hiệu lực tối thiểu, không phải yêu cầu chờ một giờ hay cam kết mọi liên kết đều hỏng đúng lúc tròn một giờ. Gọi lại getFile sau khi hết hạn là cách lấy liên kết mới được tài liệu hướng dẫn.

Lưu tệp sau khi tiếp nhận dữ liệu bền vững

Dưới đây là kiến trúc ứng dụng được đề xuất, không phải bảo đảm phân phối của Telegram:

1. Lưu update đã nhận cùng siêu dữ liệu đủ để tạo tác vụ tải. Ghi tác vụ vào nơi lưu trữ bền vững trước khi xác nhận tiếp nhận.
2. Để worker lấy địa chỉ ngay trước lúc tải, thay vì đưa hàng loạt URL đang mất dần thời hạn vào hàng đợi dài.
3. Truyền dữ liệu dạng luồng vào vùng lưu trữ tạm riêng tư, với giới hạn dung lượng và thời gian do bạn đặt. Coi tên tệp và MIME type của người gửi là siêu dữ liệu chưa đáng tin.
4. Chỉ cung cấp tham chiếu tới bản lưu của bạn sau khi tải và kiểm tra nội dung xong. Không đưa tệp chưa hoàn chỉnh vào giao diện hỗ trợ hoặc quy trình AI.
5. Khi lỗi, lưu nguyên nhân đã che thông tin nhạy cảm và quyết định có thử lại trong giới hạn hay không. Nếu không thể khôi phục, hiển thị “tệp đính kèm không khả dụng”, thay vì báo “chưa nhận tin nhắn”.

Dùng tên tệp hoặc object key do ứng dụng tạo, không dùng trực tiếp đường dẫn người dùng cung cấp. Giới hạn đích mạng của worker, không chuyển thông tin xác thực dịch vụ tới máy chủ tùy ý và không ghi bí mật hay URL có chữ ký vào log thông thường. Sự kiện vượt qua kiểm tra chữ ký không chứng minh tài liệu đính kèm an toàn để mở.

Nên kiểm thử tác vụ bị trễ, địa chỉ hết hạn, tệp quá lớn, thiếu tên tệp không bắt buộc và worker dừng giữa lúc ghi. Tiêu chí đạt không chỉ là HTTP thành công: đúng cuộc trò chuyện có quyền truy cập phải nhận được bản sao dùng được hoặc trạng thái lỗi rõ ràng. Đây là đề xuất kiểm thử, không phải kết quả đã thực hiện.

Tệp đính kèm UnifyPort có đặc tả khôi phục khác

Giao diện không chính thức của UnifyPort cung cấp sự kiện message.received đã chuẩn hóa cho các tài khoản nhắn tin được kết nối. Tài liệu sự kiện chuẩn mô tả data.message.attachments[] và URL OSS có chữ ký tạm thời. Hướng dẫn ánh xạ trường tệp Telegram giải thích dữ liệu cần lưu; bài này tập trung vào khả năng truy cập tệp sau khi tạo tác vụ tải.

Với luồng này:

• Xác minh chữ ký và lưu sự kiện bền vững theo tài liệu phân phối webhook, rồi xử lý sớm các URL khả dụng theo chính sách lưu giữ của bạn.
• Xử lý rõ trường hợp không có URL. Cách biểu diễn tệp quá lớn trong tài liệu dùng attachments[].metadata.is_big_file và bỏ url; không tự tạo địa chỉ tải từ mã tin nhắn.
• Không giả định tệp đính kèm chuẩn hóa có file_id của Bot API, cũng không đưa URL đó vào getFile.
• Không sao chép bảo đảm một giờ hay giới hạn 20 MB của Bot API vào cấu hình worker dưới dạng quy tắc sản phẩm UnifyPort.

Tài liệu công khai của UnifyPort không mô tả endpoint làm mới URL tệp đính kèm. Tài liệu cũng nêu rằng không có REST API đọc lịch sử tin nhắn hoặc bảo đảm phát lại payload đã bỏ lỡ. Nếu URL không còn dùng được và bạn chưa lưu bản sao, đừng hứa rằng kết nối lại tài khoản sẽ khôi phục tệp. Hãy ghi nhận giới hạn và khi cần, thu xếp gửi lại với quyền phù hợp hoặc xử lý thủ công.

Câu hỏi thường gặp

Có dùng file_unique_id với getFile được không?

Không. Telegram nêu rõ mã này không dùng để tải hoặc tái sử dụng tệp. Hãy giữ file_id cho quy trình tải xuống.

Liên kết luôn hết hạn đúng sau một giờ?

Không nhất thiết. Telegram bảo đảm hiệu lực ít nhất một giờ. Khi hết hạn, yêu cầu liên kết mới qua getFile.

Có nên gửi URL gốc cho trình duyệt hoặc dịch vụ AI?

Ưu tiên tải ở backend rồi cung cấp tham chiếu lưu trữ có kiểm tra quyền trong ứng dụng. Không để lộ thông tin xác thực hay chia sẻ rộng URL có chữ ký tạm thời chỉ để hiển thị tệp đính kèm.

getFile có làm mới URL tệp đính kèm UnifyPort không?

Không có đặc tả nào mô tả khả năng tương tác đó. Làm theo hợp đồng của từng giao diện và không tự giả định có thao tác làm mới.

Bước tiếp theo và nguồn tham khảo

Xem đặc tả sự kiện webhook chuẩn và bổ sung trạng thái lưu tệp thành công hoặc thất bại rõ ràng cho worker trước khi nối vào quy trình tự động hóa phía sau.

Nguồn được kiểm tra ngày 2026-09-24:

• Telegram Bot API: getFile, File, Document và máy chủ cục bộ
• Telegram Bots FAQ: xử lý nội dung đa phương tiện
• UnifyPort: loại sự kiện chuẩn và payload
• UnifyPort: phân phối và xác minh chữ ký