Sign inGet started

WhatsApp 音频消息

音频消息携带一个公开 URL,WhatsApp 在发送时获取该 URL。它没有标题文字,可以选择以语音备忘录形式呈现。

发送音频消息

设置 audio.url
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  audio: { url: "https://cdn.example.com/vm/9f2.ogg" },
});
console.log(msg.id, msg.status);
完整结构添加了可选的 voice 标志,这是 audio 仅有的另一个字段:
代码示例
{
  "to": "+16505551234",
  "from": "+13124495648",
  "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}
audio 没有 caption 字段。from 在每条服务消息中都是必需的:必须是你的工作区拥有的号码,而非 Bird 托管的号码。

限制

字段限制值执行方
文件大小16 MB仅 WhatsApp,在获取时(异步)
格式AAC、AMR、MP3、M4A,或使用 OPUS 编解码器的 OGG,单声道仅 WhatsApp,在获取时(异步)
voice: true要求 .ogg/OPUS,单声道;其他格式会导致转录失败仅 WhatsApp,在获取时(异步)
caption不是有效字段Bird,在接受时(422,schema 拒绝)
url绝对路径,https,包含主机名,无原始空格Bird,在接受时(422
Bird 在入队之前检查 URL 的格式;它不会检查文件的实际大小、格式或编解码器,也不会检查 voice: true 发送是否确实是 .ogg/OPUS。只有 WhatsApp 在发送时自行获取文件才能做到。在音频消息上发送 caption 不是长度错误;该字段在此分支的 schema 中不存在,因此会作为无法识别的属性而失败。请参阅中心的通过 URL 发送媒体媒体失败时的处理

读取入站音频消息

入站音频消息携带相同的 audio 对象,外加一个 idmime_type(Bird 在获取文件时获知),且双向都没有 caption。请参阅接收 WhatsApp 音频以了解完整的入站读取方式、whatsapp.received 载荷以及需要注意的事项。

限制与失败模式

  • 客户服务窗口必须处于打开状态。 音频是服务消息,只有在打开的窗口内才能投递;请参阅中心的客户服务窗口
  • Bird 拒绝 http;WhatsApp 本身会去获取它。 请参阅中心的通过 URL 发送媒体以了解完整的格式检查。
  • 被拒绝的获取仍然会产生费用。 请参阅中心的媒体失败时的处理。音频被 WhatsApp 拒绝时的具体错误文本尚未被独立验证,因此该映射应视为基于对称性推断,而非逐项确认。
  • voice 标志改变的是接收者客户端呈现消息的方式,而非 Bird 验证的内容。 voice: true 将其呈现为语音备忘录:自动下载、显示内联麦克风图标,并可被转录。要实现此效果,需要使用 OPUS 编码的 .ogg 单声道文件;其他格式仍可发送,但转录会在接收端失败。voice 默认为 false
  • WhatsApp 自身的播放图标阈值和 "played" 信号不是 Bird 会暴露的内容。 WhatsApp 记录了一种关于小语音备忘录和已播放状态的客户端行为,但 Bird 不对这两者建模;不要构建期望从 API 读取这些信息的集成。
  • WhatsApp 会将获取过的 URL 缓存约 10 分钟。 在该窗口内重新发送相同的 URL 会复用首次获取的结果;更改 URL 可强制进行新的获取。

后续步骤