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 跑通發送，再用標準事件將所有入站訊息接返去業務系統。