# WhatsApp 文档消息

文档消息携带一个公开 URL，WhatsApp 在发送时拉取该 URL，可附带可选的标题和可选的文件名。它是最大的媒体类型，也是唯一同时支持标题和文件名的类型。

## 发送文档

设置 `document.url`：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/message-types/documents.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/message-types/documents.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/message-types/documents.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/message-types/documents.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/message-types/documents.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/message-types/documents.curl.md)

完整结构还包含 `caption` 和 `filename`：

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "document": {
    "url": "https://cdn.example.com/invoices/a1b2c3.pdf",
    "caption": "Your invoice for order A1B2C3",
    "filename": "invoice-a1b2c3.pdf"
  }
}
```

`from` 在每条服务消息中都是必填项：必须是你的工作区拥有的号码，而非 Bird 托管的号码。

## 限制

| 字段       | 限制                                                                                            | 执行方                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 文件大小   | 100 MB                                                                                          | 仅 WhatsApp，在拉取时（异步）                                                       |
| 文件类型   | PDF、Word、Excel、PowerPoint 或纯文本可在 WhatsApp 客户端中可靠呈现；其他类型会被传输但不受支持 | 仅 WhatsApp，在拉取时（异步）                                                       |
| `caption`  | 最多 1024 个字符                                                                                | Bird，在接受时（`422`）                                                             |
| `filename` | 1 到 100 个字符                                                                                 | Bird，在接受时（`422`）；此上限为 Bird 自定，因为 WhatsApp 未记录任何文件名长度限制 |
| `url`      | 绝对路径、`https`、包含主机名、无原始空格                                                       | Bird，在接受时（`422`）                                                             |

Bird 会在入队前检查 URL 的格式以及标题和文件名的长度。它不会检查文件的实际大小或类型；只有 WhatsApp 在发送时自行拉取才能检查。参见中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)和[媒体失败时](/docs/guides/whatsapp/message-types#when-media-fails)。

## 读取入站文档

入站文档携带相同的 `document` 对象，外加一个 `id` 和 `mime_type`，这些是 Bird 在拉取文件时获取的。两者在出站回读中均不存在，因为 Bird 从未拉取过它发送的文件，而入站消息中的 `filename` 是联系人设备提供的值。参见[接收 WhatsApp 文档](/docs/guides/whatsapp/receiving-whatsapp/documents)了解完整的入站读取、`whatsapp.received` 载荷以及注意事项。

## 限制与失败模式

- **客户服务窗口必须处于打开状态。** 文档属于服务消息，只能在打开的窗口内送达；参见中心的[客户服务窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。
- **Bird 拒绝 `http`；WhatsApp 本身会去拉取。** 参见中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)了解完整的格式检查。
- **拉取被拒仍会产生费用，而文档是最容易遇到这种情况的媒体类型。** 文档上限为 100 MB，是你能发送的最大内容，而 Bird 在接受时不检查实际字节。参见中心的[媒体失败时](/docs/guides/whatsapp/message-types#when-media-fails)了解 `media_rejected` 以及失败仍计费的事实。文档自身来自 WhatsApp 的拒绝文本尚未像图片那样被独立验证，因此应将该映射视为对称推断而非逐因确认。
- **省略 `filename` 不意味着收件人看不到文件名。** WhatsApp 会从 URL 路径中派生一个名称，可能是不可读的哈希或 slug。显式设置 `filename` 以控制实际显示的名称。
- **100 个字符的 `filename` 上限是 Bird 自己的选择，而非 WhatsApp 的限制。** WhatsApp 完全没有记录任何文件名长度限制。
- **WhatsApp 会缓存已拉取的 URL 约 10 分钟。** 在该时间窗口内重新发送相同的 URL 会复用首次拉取的结果；更改 URL 以强制重新拉取。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口以及所有服务消息共享的模型
- [图片](/docs/guides/whatsapp/message-types/images)：用于发送照片或图形而非文件
- [模板](/docs/guides/whatsapp/templates)：用于在窗口关闭后发送消息
- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：请求信封、`202` 模型以及安全重试

## 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)