接收 WhatsApp 文档

联系人附加的 PDF、电子表格或任何其他文件，会以携带 document 的入站消息形式到达：其中包含共享媒体引用，以及联系人设备为该文件提供的名称。

入站文档包含的内容

代码示例

{
  "id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "document": {
    "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "mime_type": "application/pdf",
    "filename": "invoice-A1B2C3.pdf"
  },
  "created_at": "2026-08-25T09:15:02Z"
}

字段	包含内容
id	已存储的文件，获取字节时作为 media_id 传入
url	一个 Bird URL，使用你的 API 密钥获取
mime_type	WhatsApp 报告的该文件的媒体类型，例如 application/pdf
filename	发送者为文件指定的名称；如果消息中未携带则为空
caption	联系人在文档下方输入的文字；如果未输入则为空

filename 是发送方和接收方用法不同的唯一字段：发送时它是你希望在聊天中显示的名称，在入站消息中则是联系人设备提供的任意值。

获取字节

将消息 ID 和媒体 id 传入渠道的媒体方法。Hub 的获取入站媒体文档包含各语言的调用示例，以及它遵循的重定向和请求头规则，并说明了文件的保留时限。

不要在收到 filename 时直接将其写入磁盘。 它是来自未经身份验证的发送者的攻击者可控文本：可能包含路径分隔符、目录遍历序列、误导性的双重扩展名，或与你已有文件同名的名称。使用媒体 id 生成你自己的存储键，将 filename 仅作为显示标签，并根据 mime_type 而非名称中声称的扩展名来决定如何处理文件。

Webhook 载荷

whatsapp.received 在事件信封上携带 document 分支：

代码示例

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:15:02.336Z",
  "data": {
    "whatsapp_id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "document": {
      "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "mime_type": "application/pdf",
      "filename": "invoice-A1B2C3.pdf"
    },
    "tags": null,
    "metadata": null
  }
}

收集材料的理赔或入驻流程可以在此处根据 mime_type 进行路由并将获取操作加入队列，因为在整个保留时限内字节始终可用。

注意事项

mime_type 是 WhatsApp 对文件的报告，不能说明文件内部的实际内容。 对从联系人接收的任何文件进行扫描，并在解析之前验证文件自身的结构。
说明文字和文件名是不同的字段。 联系人在附加文件时输入的备注会填入 caption；filename 仍然来自其设备。

后续步骤

接收消息的工作原理：入站信封、媒体获取以及 whatsapp.received webhook
WhatsApp 文档消息：同一分支的发送端
接收图片：用于文档照片的相同媒体结构
WhatsApp 事件：完整的事件列表，通过 API 或 webhooks 获取