Sign inGet started

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);
完整结构可添加一个可选的 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 对象,外加一个 idmime_type,这些是 Bird 抓取文件后获知的信息。在出站回读中两者均不存在,因为 Bird 从未抓取它发送的文件。参阅接收 WhatsApp 图片了解完整的入站读取方式、whatsapp.received 载荷以及需要注意的事项。

限制与失败模式

  • 客户服务窗口必须处于打开状态。 图片属于服务消息,只有在窗口打开期间才能投递;参阅中心的客户服务窗口
  • Bird 会拒绝 http;WhatsApp 本身会去抓取它。 该区别及 URL 格式检查的其余内容见中心的通过 URL 发送媒体
  • 文件过大、MIME 类型错误或 URL 无法访问都会以相同方式失败,且在你已被扣费之后。 参阅中心的媒体失败时的处理了解 media_rejected 以及失败仍计费的事实。
  • WhatsApp 会将抓取过的 URL 缓存约 10 分钟。 在该窗口内重新发送相同的 URL 会复用首次抓取的结果,而不会再次抓取;可通过改变 URL(例如添加查询参数)来强制发起新抓取。

后续步骤