WhatsApp 贴纸消息
贴纸消息携带一个公开的 WebP URL,WhatsApp 在发送时获取该文件。它是最简单的媒体类型:发送时没有标题,也没有其他可选字段。
发送贴纸
设置 sticker.url,无需添加其他内容:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
sticker: { url: "https://cdn.example.com/stickers/thumbs-up.webp" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
sticker={"url": "https://cdn.example.com/stickers/thumbs-up.webp"},
)
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",
Sticker: &bird.WhatsAppStickerSend{Url: "https://cdn.example.com/stickers/thumbs-up.webp"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$sticker = (new WhatsAppMessageSendRequestSticker())
->setUrl('https://cdn.example.com/stickers/thumbs-up.webp');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
sticker: $sticker,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--sticker https://cdn.example.com/stickers/thumbs-up.webp \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"sticker": {
"url": "https://cdn.example.com/stickers/thumbs-up.webp"
},
"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",
"sticker": {
"url": "https://cdn.example.com/stickers/thumbs-up.webp"
}
}'sticker 没有 caption 字段,animated 也不是你在发送时设置的;Bird 仅在收到贴纸时将其返回。from 是每条服务消息的必填项:必须是你的工作区拥有的号码,而不是 Bird 托管的号码。
限制
| 字段 | 限制值 | 执行方 |
|---|---|---|
| 文件大小,静态 | 100 KB | 仅 WhatsApp,在获取时(异步) |
| 文件大小,动态 | 500 KB | 仅 WhatsApp,在获取时(异步) |
| 文件类型 | 仅限 WebP | 仅 WhatsApp,在获取时(异步) |
| caption | 无效字段 | Bird,在接受时(422,schema 拒绝) |
| url | 绝对路径、https、包含主机、无原始空格 | Bird,在接受时(422) |
Bird 在入队之前检查 URL 的格式;它不检查文件的实际大小、格式,也不判断文件是静态还是动态的。只有 WhatsApp 在发送时自行获取文件才能做到。发送 caption 不是长度错误;该字段在此类型的 schema 中不存在,因此会作为无法识别的属性而失败。参见中心的通过 URL 发送媒体和媒体发送失败时。
读取收到的贴纸
收到的贴纸携带 id、mime_type 和 animated,这些是 Bird 通过获取文件得到的信息。在已发送消息的回读中,这三项均不存在,因为 Bird 从未获取或检查过它发送的文件。参见接收 WhatsApp 贴纸了解完整的接收读取、whatsapp.received 载荷以及注意事项。
限制与失败模式
- 客户服务窗口必须处于打开状态。 贴纸属于服务消息,只能在打开的窗口内投递;参见中心的客户服务窗口。
- Bird 拒绝 http;WhatsApp 本身会去获取它。 参见中心的通过 URL 发送媒体了解完整的格式检查。
- 被拒绝的获取仍然会被计费。 参见中心的媒体发送失败时。WhatsApp 对贴纸自身的拒绝文案尚未经过独立验证,因此该映射应视为类推推断,而非逐项确认。
- animated 是只读的,仅出现在收到的或已获取的贴纸上。 它是 WhatsApp 对文件的判定结果,不是你可以声明的值。贴纸是静态还是动态仅影响其大小上限;无论哪种都必须是 WebP 格式。
- WhatsApp 会将已获取的 URL 缓存约 10 分钟。 在此窗口内重新发送相同的 URL 会复用首次获取的结果;更改 URL 以强制重新获取。
后续步骤
- WhatsApp 服务消息:客户服务窗口以及所有服务消息共享的模型
- 音频:另一种没有标题字段的媒体类型
- 图片:用于带标题的照片或图形
- 发送 WhatsApp 消息:请求信封、202 模型以及安全重试