Sign inGet started

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);
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 发送媒体媒体发送失败时

读取收到的贴纸

收到的贴纸携带 idmime_typeanimated,这些是 Bird 通过获取文件得到的信息。在已发送消息的回读中,这三项均不存在,因为 Bird 从未获取或检查过它发送的文件。参见接收 WhatsApp 贴纸了解完整的接收读取、whatsapp.received 载荷以及注意事项。

限制与失败模式

  • 客户服务窗口必须处于打开状态。 贴纸属于服务消息,只能在打开的窗口内投递;参见中心的客户服务窗口
  • Bird 拒绝 http;WhatsApp 本身会去获取它。 参见中心的通过 URL 发送媒体了解完整的格式检查。
  • 被拒绝的获取仍然会被计费。 参见中心的媒体发送失败时。WhatsApp 对贴纸自身的拒绝文案尚未经过独立验证,因此该映射应视为类推推断,而非逐项确认。
  • animated 是只读的,仅出现在收到的或已获取的贴纸上。 它是 WhatsApp 对文件的判定结果,不是你可以声明的值。贴纸是静态还是动态仅影响其大小上限;无论哪种都必须是 WebP 格式。
  • WhatsApp 会将已获取的 URL 缓存约 10 分钟。 在此窗口内重新发送相同的 URL 会复用首次获取的结果;更改 URL 以强制重新获取。

后续步骤