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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
document={"url": "https://cdn.example.com/invoices/a1b2c3.pdf"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Document: &bird.WhatsAppDocumentSend{Url: "https://cdn.example.com/invoices/a1b2c3.pdf"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$document = (new WhatsAppMessageSendRequestDocument())
->setUrl('https://cdn.example.com/invoices/a1b2c3.pdf');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
document: $document,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--document https://cdn.example.com/invoices/a1b2c3.pdf \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
}
}'完整结构还包含 caption 和 filename:
代码示例
{
"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 发送媒体和媒体失败时。
读取入站文档
入站文档携带相同的 document 对象,外加一个 id 和 mime_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 以强制重新拉取。
后续步骤
- WhatsApp 服务消息:客户服务窗口以及所有服务消息共享的模型
- 图片:用于发送照片或图形而非文件
- 模板:用于在窗口关闭后发送消息
- 发送 WhatsApp 消息:请求信封、202 模型以及安全重试