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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
audio={"url": "https://cdn.example.com/vm/9f2.ogg"},
)
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",
Audio: &bird.WhatsAppAudioSend{Url: "https://cdn.example.com/vm/9f2.ogg"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$audio = (new WhatsAppMessageSendRequestAudio())
->setUrl('https://cdn.example.com/vm/9f2.ogg');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
audio: $audio,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--audio https://cdn.example.com/vm/9f2.ogg \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
},
"from": "+13124495648",
"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",
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
}
}'完整结构添加了可选的 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 对象,外加一个 id 和 mime_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 可强制进行新的获取。
后续步骤
- WhatsApp 服务消息:客户服务窗口以及所有服务消息共享的模型
- 视频:用于发送视频片段而非音频
- 贴纸:另一个没有标题文字字段的媒体分支
- 发送 WhatsApp 消息:请求信封、202 模型以及安全重试