Sign inGet started

WhatsApp 文档消息

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

发送文档

设置 document.url
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);
完整结构还包含 captionfilename
代码示例
{
  "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
filename1 到 100 个字符Bird,在接受时(422);此上限为 Bird 自定,因为 WhatsApp 未记录任何文件名长度限制
url绝对路径、https、包含主机名、无原始空格Bird,在接受时(422
Bird 会在入队前检查 URL 的格式以及标题和文件名的长度。它不会检查文件的实际大小或类型;只有 WhatsApp 在发送时自行拉取才能检查。参见中心的通过 URL 发送媒体媒体失败时

读取入站文档

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

限制与失败模式

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

后续步骤