WhatsApp API媒体消息：支持的文件类型与大小限制

支持哪些文档格式？

文档可以是PDF、Word、Excel、PowerPoint或纯文本，最大100 MB。

文档消息可以带一个含扩展名的可选文件名，WhatsApp客户端会根据该扩展名选择文件图标。请取一个易读的名称，例如invoice-2026-1042.pdf，因为客户会看到它。

应该上传媒体还是发送链接？

Meta建议先上传文件，再发送其媒体ID。您也可以改为发送指向公共服务器上文件的链接，但Meta在图片、视频和文档的参考文档中都说，为了更好的性能应优先使用已上传的ID；在其吞吐量指南中，对大批量发送也是同样的建议。

使用Meta自己的端点时，上传是向/<PHONE_NUMBER_ID>/media发起POST，附上文件、其MIME类型和messaging_product=whatsapp，响应为{"id": "<MEDIA_ID>"}。上传的文件会加密保存30天，除非您提前删除。

在OmniChannels.ai的WhatsApp端点上，媒体消息接受mediaUrl（公共HTTPS URL）或mediaFile（随请求上传的文件），说明文字放在content中。请参阅WhatsApp API文档。大批量发送时，账户如何处理媒体的存储与复用，请咨询我们的团队。

媒体ID的有效期是多久？

Meta规定：上传所返回的ID为30天，入站Webhook中收到的ID为7天。通过ID取得的下载URL在5分钟后失效。

实际影响如下：

• 不要把媒体ID缓存数月。请保存原始文件，在ID被拒绝时重新上传。
• 事件一到就下载入站文件，并保留自己的副本。
• 不要保存取得的下载URL；需要时再请求新的。

媒体消息可以加说明文字吗？

可以。据Meta的消息参考文档，图片、视频和文档消息接受一个可选的说明文字，最长1,024个字符。说明文字是紧挨着文件的纯文本。

在这一模型中，音频和贴纸消息没有说明文字。如果语音消息需要配文字，请在旁边另发一条简短的文本消息。在客户服务窗口内，说明文字可以自由编写；窗口之外，媒体必须放在已获批的模板中发送。

消息模板中的媒体如何使用？

模板的头部可以放图片、视频或文档，且该头部在创建模板时就已确定。提交模板审核时需要提供示例文件，发送时则可以提供实际文件。

在我们的API中，创建时headerFormat可以是IMAGE、VIDEO或DOCUMENT，headerFile用于传递示例，发送时的mediaUrl会覆盖头部媒体。示例文件的要求请查阅Meta的模板文档。请参阅模板类别与审核和模板示例。

如何下载客户发来的媒体？

入站媒体以带有媒体ID的Webhook形式到达；您需要把它解析为URL，并带授权下载。

1. 从入站消息事件中读取媒体ID。
2. 请求该ID对应的媒体URL。Meta的响应包含url、mime_type、sha256和file_size。
3. 向该URL发送GET请求，并带上Authorization: Bearer <token>请求头。没有令牌，请求会失败。
4. 检查Content-Type请求头和sha256值，然后保存文件。
5. 如果返回404，请求新的URL并重试；若仍失败，请更新访问令牌。

Meta在Cloud API上的入站媒体最大为100 MB。更大的文件会触发带有错误码131052的Webhook；请让客户发送更小的文件，或用其他方式分享。在内部打开之前，请扫描每个文件。请参阅Webhook指南，并向您的开通工程师确认入站媒体在您账户上是如何投递的。

示例：牙科诊所发送报告

开罗的"Nile Smile Clinic"（虚构）会发送预约卡和X光报告。

1. 预约卡是300 KB的PNG图片，配两行说明文字，远低于5 MB。
2. 治疗报告是2到8 MB的PDF，命名为report-2026-0381.pdf，以文档形式发送。
3. 一段25 MB的诊所介绍视频超出视频上限。团队将其重新编码为H.264/AAC的MP4，加上faststart，大小控制在16 MB以内。
4. 患者发来处方照片。收件箱会立即下载每个文件，因为入站ID在7天后过期。
5. 语音问候被导出为单声道Opus OGG，因为其他OGG变体会被拒绝。

常见错误有哪些？

• **只看大小。**一张色彩格式不对的3 MB图片，或编码有误的视频，照样会失败。
• **MIME不匹配。**把.jpg以application/octet-stream提供，是错误131053的典型原因。
• **链接指向缓慢或私有的URL，**例如已过期的签名链接，或需要登录才能访问的页面。
• **依赖旧的媒体ID。**ID在30天后过期。
• **忽视入站过期。**客户的文件必须在7天内保存。
• **把动态WebP当图片发送。**它会被拒绝；请改用贴纸或视频。
• **限制会变化。**硬编码校验之前，请重新核对Meta的参考文档。

OmniChannels.ai如何提供帮助

OmniChannels.ai通过一个API发送WhatsApp图片、视频、音频、文档和贴纸消息，支持公共链接或上传文件并附说明文字，也会在共享收件箱中显示媒体和附件。BroadNet是Meta官方的商业解决方案提供商（Business Solution Provider），因此带图片、视频或文档头部的模板可以创建，并跟踪其审核状态。请阅读WhatsApp API文档和错误与限制，或了解WhatsApp渠道。