Telegram getFile 下載連結過期：安全恢復附件下載
Telegram 機器人的檔案下載連結過期後，請使用檔案的 file_id 再次呼叫 getFile，依照新回傳的 file_path 下載。Telegram 保證準備好的連結至少有效一小時，並非永久有效。不要把 file_unique_id 當成下載識別碼。這個復原方法適用於官方 Bot API；統一 webhook 傳來的暫時性附件 URL 採用另一套契約。
重點
- 收到媒體訊息，不代表應用程式已保存檔案內容。
- 保留檔案識別碼及訊息脈絡，將下載 URL 視為暫時位置。
- Bot API 連結過期時重新呼叫
getFile，不要無限重試舊 URL。 - 不要將 Telegram 的有效期限或更新方法套用到 UnifyPort 附件。
getFile 回傳什麼，應該保存什麼
Telegram Bot API 參考文件將 getFile 定義為取得檔案基本資訊並準備下載的方法，成功時回傳 File 物件。以下欄位不能混用：
| 欄位 | 官方用途 | 建議的應用處理 |
|---|---|---|
file_id | 下載或重複使用檔案 | 與接收機器人的身分一起保存，供後續 getFile 使用 |
file_unique_id | 跨時間、不同機器人識別檔案，但不能下載或重複使用 | 可用於關聯，不可代替下載識別碼 |
file_path | 下載已準備檔案所用的路徑 | 採用最新回應，不把舊路徑當永久位址 |
file_name、mime_type | 傳送者提供的選填文件中繼資料 | 原訊息有提供時保存，使用前驗證 |
也要保留原始聊天室及訊息識別碼。檔案身分不等於聊天室存取權：其他聊天室出現相同媒體，不應自動取得已保存副本的存取權限。
這些是 Bot API 欄位，不是 UnifyPort 事件結構的新欄位。尚未決定串接方式時，先閱讀 Bot API webhook 與統一入站 webhook 比較。
先找出 Telegram 檔案下載失敗的階段
收件匣顯示縮圖，不代表檔案已保存。請依實際失敗的環節選擇處理方式。
| 現象 | 接著檢查 | 復原界線 |
|---|---|---|
getFile 失敗 | 機器人憑證、實際 file_id、錯誤回應及檔案大小 | 先修正請求或選擇支援的下載方式 |
| 原本可用的連結失效 | 取得新的 getFile 回應 | 用新位置重試；不能將所有 HTTP 錯誤都判定為過期 |
| 下載逾時 | 網路、背景工作逾時、儲存空間可用性 | 限次重試；懷疑過期時重新取得位置 |
| 下載成功但解析失敗 | 實際內容與解析器支援情況 | 更新連結不能修復不支援或無效的內容 |
| webhook 已收到，卻沒有自有檔案 | 持久化下載工作與執行結果 | 事件接收及檔案保存是不同里程碑 |
Telegram 目前在 API 文件與 Bots FAQ說明，代管 Bot API 的檔案下載上限為 20 MB。這不是上傳限制，也不能代表所有 Telegram 用戶端的能力。API 文件另有本機 Bot API 伺服器不受該下載大小限制的說明；那是基礎架構選擇，不是加一個參數就能讓代管端點下載較大檔案。
「至少一小時」是最低有效期限保證，不是要求等待一小時，也不是保證所有連結恰好於一小時後失效。過期後再次呼叫 getFile 取得新連結，才是文件列出的復原方法。
可靠接收之後，再處理檔案保存
以下是建議的應用架構，不是 Telegram 的交付保證：
- 保存收到的更新，以及建立下載工作所需的檔案中繼資料。工作已持久化後，再確認接收成功。
- 由背景工作在即將下載時取得位置，不要讓大量暫時 URL 在長佇列中逐漸過期。
- 串流寫入私有暫存空間，設定自己的位元組與時間限制。傳送者的檔名和 MIME 類型都應視為不可信資料。
- 下載與內容檢查完成後，才發布自有儲存參照。尚未完成的檔案不能進入客服介面或 AI 處理。
- 失敗時保留去識別化的原因，並決定是否有限重試。無法復原時顯示「附件無法使用」，不要誤報「未收到訊息」。
使用應用程式產生的物件鍵或檔名，不直接使用使用者提供的路徑。限制下載工作的網路目的地，不向任意主機轉送服務憑證，也不要在一般日誌記錄憑證或簽署 URL。事件通過簽章驗證，不代表附件可以安全開啟。
建議驗收案例包括：工作延遲、位置過期、檔案過大、缺少選填檔名，以及儲存過程中工作程序中斷。成功標準不只是 HTTP 請求成功，而是正確且經授權的聊天室取得可用副本或明確失敗狀態。這是測試建議，不是實測結果。
UnifyPort 附件的復原契約不同
UnifyPort 以非官方介面連接訊息帳號，傳送標準化的 message.received 事件。標準事件文件說明 data.message.attachments[] 與暫時性 OSS 簽署 URL。Telegram 媒體欄位對應指南處理欄位保存；本文則聚焦下載工作建立後的檔案可用性。
這條路徑請注意：
- 依投遞文件驗證簽章並持久接收事件，再按照保留政策及時處理可用附件 URL。
- 明確處理沒有 URL 的情況。文件中的超大檔案表示使用
attachments[].metadata.is_big_file並省略url；不要由訊息 ID 自行組合下載位址。 - 不要假設標準化附件提供 Bot API
file_id，也不要把附件 URL 交給getFile。 - 不要將 Bot API 的一小時保證或 20 MB 上限寫成 UnifyPort 的產品規則。
UnifyPort 公開文件沒有列出附件 URL 更新端點，也明確說明沒有 REST 訊息歷史讀取 API，且不保證遺漏載荷可重播。若 URL 已失效而你沒有自有副本，不要承諾重新連線帳號就能復原。請記錄限制，必要時安排經授權的重新傳送或人工處理。
常見問題
file_unique_id 可以傳給 getFile 嗎？
不可以。Telegram 明確說明它不能用來下載或重複使用檔案。下載流程要保留 file_id。
下載連結一定一小時後過期嗎？
不一定。保證的是至少有效一小時。過期後以 getFile 請求新連結。
應直接將原始下載 URL 交給瀏覽器或 AI 服務嗎？
優先由後端下載，再提供經應用程式授權的儲存參照。不要為了顯示附件而暴露憑證，或廣泛分享暫時性簽署 URL。
getFile 能更新 UnifyPort 附件 URL 嗎？
文件沒有這種互通承諾。遵循各介面的契約，不要自行假設存在更新操作。
下一步與參考資料
先檢查標準 webhook 事件契約，在串接下游自動化前，為媒體工作程序加入明確的保存成功與失敗狀態。
資料核對日期：2026-09-24。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送，再用標準事件把所有入站訊息接回業務系統。