# 接收 WhatsApp 文档

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

## 入站文档包含的内容

```json
{
  "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 的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)文档包含各语言的调用示例，以及它遵循的重定向和请求头规则，并说明了文件的保留时限。

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

## Webhook 载荷

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

```json
{
  "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` 仍然来自其设备。

## 后续步骤

- [接收消息的工作原理](/docs/guides/whatsapp/receiving-whatsapp)：入站信封、媒体获取以及 `whatsapp.received` webhook
- [WhatsApp 文档消息](/docs/guides/whatsapp/message-types/documents)：同一分支的发送端
- [接收图片](/docs/guides/whatsapp/receiving-whatsapp/images)：用于文档照片的相同媒体结构
- [WhatsApp 事件](/docs/guides/whatsapp/events)：完整的事件列表，通过 API 或 webhooks 获取

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)