← 所有文章
指南

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 contentwebhook 提供中繼資料,不是二進制檔案
contentProvider.type: external 的圖片、影片或音訊使用 contentProvider.originalContentUrlGet 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 只證明你記錄了識別碼,不代表日後仍能取得檔案。

建議處理順序:

  1. 驗證來源並持久化接收事件,保留 channel 與訊息背景資料。
  2. 儲存記錄時一併建立可恢復的媒體工作。LINE 批次事件接收指南說明為何不能只接收請求中的部分事件就回報成功。
  3. 按正確來源下載原始檔案,交給客服或 AI 工具前先套用容量上限、逾時及內容檢查。
  4. 保存應用程式自有的儲存參照,並按對話權限控制存取。檔名及宣告的媒體類型都應視為不可信輸入。
  5. 無法完成下載時明確顯示「附件無法使用」,有需要時請用戶在授權範圍內重新傳送。

外部 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。

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。