WhatsApp 图片消息
图片消息携带一个公开 URL,WhatsApp 在发送时抓取该 URL 指向的文件,下方可附带可选的说明文字。
发送图片
设置 image.url:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
image={"url": "https://cdn.example.com/receipt.png"},
)
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",
Image: &bird.WhatsAppImageSend{Url: "https://cdn.example.com/receipt.png"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$image = (new WhatsAppMessageSendRequestImage())
->setUrl('https://cdn.example.com/receipt.png');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
image: $image,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--image https://cdn.example.com/receipt.png \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipt.png"
},
"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",
"image": {
"url": "https://cdn.example.com/receipt.png"
}
}'完整结构可添加一个可选的 caption:
代码示例
{
"to": "+16505551234",
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipts/a1b2c3.png",
"caption": "Your receipt for order A1B2C3"
}
}image 没有 filename 字段。每条服务消息都必须设置 from:你的工作区拥有的号码,而非 Bird 托管的号码。
限制
| 字段 | 限制 | 校验方 |
|---|---|---|
| 文件大小 | 5 MB | 仅 WhatsApp,抓取时(异步) |
| 文件类型 | JPEG 或 PNG | 仅 WhatsApp,抓取时(异步) |
| caption | 最多 1024 个字符 | Bird,接受时(422) |
| url | 绝对路径、https、包含主机名、无原始空格 | Bird,接受时(422) |
Bird 在入队之前会检查 URL 的格式和说明文字的长度。它不会检查文件的实际大小或类型;只有 WhatsApp 在发送时的抓取才能做到。参阅中心的通过 URL 发送媒体了解格式检查的覆盖范围,以及媒体失败时的处理了解 WhatsApp 抓取拒绝文件后的情况。
读取入站图片
入站图片携带相同的 image 对象,外加一个 id 和 mime_type,这些是 Bird 抓取文件后获知的信息。在出站回读中两者均不存在,因为 Bird 从未抓取它发送的文件。参阅接收 WhatsApp 图片了解完整的入站读取方式、whatsapp.received 载荷以及需要注意的事项。
限制与失败模式
- 客户服务窗口必须处于打开状态。 图片属于服务消息,只有在窗口打开期间才能投递;参阅中心的客户服务窗口。
- Bird 会拒绝 http;WhatsApp 本身会去抓取它。 该区别及 URL 格式检查的其余内容见中心的通过 URL 发送媒体。
- 文件过大、MIME 类型错误或 URL 无法访问都会以相同方式失败,且在你已被扣费之后。 参阅中心的媒体失败时的处理了解 media_rejected 以及失败仍计费的事实。
- WhatsApp 会将抓取过的 URL 缓存约 10 分钟。 在该窗口内重新发送相同的 URL 会复用首次抓取的结果,而不会再次抓取;可通过改变 URL(例如添加查询参数)来强制发起新抓取。
后续步骤
- WhatsApp 服务消息:客户服务窗口及所有服务消息共享的模型
- 视频:用于视频片段的相同结构
- 文档:用于 PDF、电子表格或其他文件
- 发送 WhatsApp 消息:请求信封、202 模型及安全重试