LINE 媒體下載失敗?釐清 Get Content 的 202 與外部內容
收到 LINE 媒體 webhook,不代表已取得檔案。圖片、影片和音訊應先檢查 message.contentProvider.type:line 使用官方 Get content 端點,external 則使用事件提供的原始內容 URL。影音仍在準備時回傳的 202 不是下載完成。LINE 不保證使用者內容的保存時間,請及時保存有權處理的內容,不要把訊息 ID 當成永久封存。
重點摘要
- 依內容來源選擇下載方式,不能只看媒體類型。
- Get content 使用
api-data.line.me,不是常見的api.line.me。 - webhook 接收成功、媒體就緒與檔案保存成功,是三個獨立狀態。
- 預覽圖不是原始檔案;更換串接方式不能復原已刪除的內容。
先判斷 LINE 媒體的下載來源
LINE Messaging API 參考在圖片、影片和音訊訊息中,區分 LINE 託管內容與外部內容。
| 收到的內容 | 取得方式 | 注意事項 |
|---|---|---|
contentProvider.type: line 的圖片、影片或音訊 | 用 message.id 呼叫 Get content | webhook 提供中繼資料,不是二進位檔案 |
contentProvider.type: external 的圖片、影片或音訊 | 使用 contentProvider.originalContentUrl | Get content 無法取得該外部檔案 |
| 檔案訊息 | 用訊息 ID 呼叫 Get content | 保留檔案中繼資料,不要假設每則訊息都有 contentProvider |
| 文字 | 保存 webhook 中的文字 | 沒有可供稍後重新取得該文字的 API |
通用收件匣尤其需要分清後兩項:不要因為檔案訊息缺少圖片分支要求的 contentProvider 就拒絕處理,也不要把文字訊息 ID 交給二進位下載操作。
LINE 託管媒體的請求為 GET /v2/bot/message/{messageId}/content,網域是 api-data.line.me,以 channel access token 驗證。權杖只應保留在後端。訊息 ID 必須來自與該 channel 對應、已驗證簽章的事件,不是使用者 ID、reply token 或事件 ID。
接收訊息指南也說明圖片與影片的預覽取得方式。預覽可用於載入中的介面,但不能證明原始檔案已下載或保存。
先判讀回應,再決定重試
Get content 參考指出:成功的 200 回傳二進位內容,格式由回應的 Content-Type 表示。較大的影片或音訊可能仍在準備,此時回傳 202。
| 觀察結果 | 建議處理 |
|---|---|
200 回傳二進位內容 | 串流寫入受控儲存空間、檢查內容,保存成功後才標記完成 |
取得影音時回傳 202 | 保留待處理工作,先查詢準備狀態,再安排下載 |
404 或 410 | 檢查訊息 ID、channel 歸屬、來源分支與錯誤回應;無限重試不能保證復原 |
| 外部 URL 失敗 | 檢查外部主機與 URL 可用性;LINE 內容端點不是替代下載途徑 |
| 有縮圖但沒有原始檔案 | 分別追蹤預覽與原始檔案,不要標記附件已完整保存 |
準備狀態端點為 GET /v2/bot/message/{messageId}/content/transcoding,詳見 API 參考。請遵循該端點自己的網域與回應契約,不要把二進位下載網域套用到所有請求。
建議設定有上限的輪詢排程與重試次數。這是應用程式的維運設計,不是 LINE 的完成時間保證。不能將所有成功類別的 HTTP 回應都視為檔案,也不能把準備中的回應交給圖片解碼器或語音轉錄服務。
及時保存,也要處理收回訊息
LINE 表示內容會在一段時間後自動刪除,且不保證保存期限。因此,保存訊息 ID 只證明你記錄了識別碼,不代表日後仍能取得檔案。
建議處理順序:
- 驗證來源並持久化接收事件,保留 channel 與訊息脈絡。
- 儲存記錄時一併建立可復原的媒體工作。LINE 批次事件接收指南說明為何不能只接收請求中的部分事件就回報成功。
- 依正確來源下載原始檔案,交給客服或 AI 工具前先套用容量上限、逾時與內容檢查。
- 保存應用程式自有的儲存參照,並按對話權限控管存取。檔名與宣告的媒體類型都應視為不可信輸入。
- 無法下載時明確顯示「附件無法使用」,必要時請使用者在授權範圍內重新傳送。
外部 URL 下載器應檢查目的地與重新導向、排除私有網路目標,且不得向外部主機轉送 LINE channel token。日誌避免記錄權杖與簽章 URL 的查詢參數。這些是建議的背景工作防護措施,不表示 LINE 已代為實作。
保存檔案也代表需要清理副本。請遵循 LINE 收回訊息清理流程,在發布下載結果前再次檢查刪除狀態。收回後才完成的下載,不應讓附件重新出現在收件匣。
將 UnifyPort 附件契約分開處理
UnifyPort 非官方介面提供標準化的 message.received 事件,不是原生 LINE 訊息物件。媒體欄位位於 data.message.attachments[];標準事件參考定義了暫時性簽章 OSS URL、附件類型與媒體中繼資料。
不要把標準化訊息 ID 傳給 LINE Get content,也不要假設事件包含 contentProvider。依保存政策及時處理提供的附件 URL;若沒有 URL,請記錄限制,不要自行組合。公開參考未定義附件 URL 更新端點,也不保證重播遺漏的訊息。
此獨立接收器應啟用 signing_secret,依 webhook 傳遞契約驗證原始請求本文的 HMAC-SHA256,再持久化接收。有效簽章只驗證傳遞來源,不代表附件仍可下載或適合安全處理。
若業務需要 LINE 官方帳號身分及原生內容契約,應繼續使用官方 Messaging API。UnifyPort 不是官方帳號附件的復原服務。
常見問題
202 代表 LINE 檔案下載成功嗎?
不是。影音仍在準備時,內容請求可能回傳 202 而沒有二進位資料。先查詢準備狀態,再依重試政策下載。
Get content 能下載 external 圖片嗎?
不能。contentProvider.type: external 應使用 contentProvider.originalContentUrl,並實作安全下載控制。
LINE 會保存內容幾天?
LINE 不保證時間。客服介面不應承諾固定天數內一定可以復原。
下一步與參考資料
建議測試 LINE 託管圖片、外部圖片、準備中的影音、無法取得的內容,以及下載過程中的收回訊息。這些是待執行的測試,不是已完成的結果。標準化接收可從 message.received 參考開始。
官方來源核對日期:2026-11-17。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。