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 媒体字段映射指南解决字段存储问题；本文关注下载任务创建后的文件可用性。
这条路径需要注意：
- 按照 webhook 投递文档验签并持久接收事件，然后按保留策略及时处理可用附件 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 跑通发送，再用标准事件把所有入站消息接回业务系统。