# WhatsApp 音频消息

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

## 发送音频消息

设置 `audio.url`：

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/message-types/audio.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/message-types/audio.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/message-types/audio.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/message-types/audio.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/message-types/audio.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/message-types/audio.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/message-types/audio.curl.md)

完整结构添加了可选的 `voice` 标志，这是 `audio` 仅有的另一个字段：

```json
{
  "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 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)和[媒体失败时的处理](/docs/guides/whatsapp/message-types#when-media-fails)。

## 读取入站音频消息

入站音频消息携带相同的 `audio` 对象，外加一个 `id` 和 `mime_type`（Bird 在获取文件时获知），且双向都没有 `caption`。请参阅[接收 WhatsApp 音频](/docs/guides/whatsapp/receiving-whatsapp/audio)以了解完整的入站读取方式、`whatsapp.received` 载荷以及需要注意的事项。

## 限制与失败模式

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

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口以及所有服务消息共享的模型
- [视频](/docs/guides/whatsapp/message-types/video)：用于发送视频片段而非音频
- [贴纸](/docs/guides/whatsapp/message-types/stickers)：另一个没有标题文字字段的媒体分支
- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：请求信封、`202` 模型以及安全重试

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)