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 查询参数。这些是建议的 worker 防护措施,不代表 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 跑通发送,再用标准事件把所有入站消息接回业务系统。