# 接收 WhatsApp 音频

联系人发送的音频以携带 `audio` 的入站消息形式到达。该分支涵盖在聊天中录制的语音备忘录和附加的音频文件，`voice` 用于区分两者。

## 入站音频包含的内容

```json
{
  "id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "audio": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "audio/ogg; codecs=opus",
    "voice": true
  },
  "created_at": "2026-08-25T09:07:32Z"
}
```

| 字段        | 包含的内容                                                           |
| ----------- | -------------------------------------------------------------------- |
| `id`        | 已存储的文件，获取字节时作为 `media_id` 传入                         |
| `url`       | 一个 Bird URL，使用你的 API 密钥获取                                 |
| `mime_type` | WhatsApp 报告的媒体类型，例如语音备忘录对应 `audio/ogg; codecs=opus` |
| `voice`     | 在聊天中录制的语音备忘录为 `true`，而非附加的音频文件                |

该分支在收发两个方向上都不存在 `caption`，因此音频消息不会附带文本。联系人如需添加文字，需另外发送一条[文本消息](/docs/guides/whatsapp/receiving-whatsapp/plain-text)。

语音备忘录会在 WhatsApp 客户端中自动下载，并可为接收者转录。Bird 直接透传音频，不进行转录，因此联系人在自己的应用中看到的转录内容不属于你读取到的消息。

## 获取字节

将消息 ID 和媒体 `id` 传给频道的媒体方法。Hub 的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)页面包含该调用的每种语言示例，以及其遵循的重定向和请求头规则。

`mime_type` 标明容器格式和编解码器，语音备忘录使用 Ogg 容器中的 Opus 编码，而附件通常是 MP3 或 AAC。应从字段读取类型，而非从 `url` 中的文件扩展名读取（该 URL 不带扩展名），并在将字节交给仅支持部分格式的转录服务之前检查类型。消息及其媒体在消息到达 30 天后一同过期；Hub 的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)页面说明了该时间窗口以及过期后读取请求的返回内容。

## Webhook 载荷

`whatsapp.received` 在事件信封上携带 `audio` 分支，包含 `voice` 标志：

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:07:32.451Z",
  "data": {
    "whatsapp_id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "audio": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "audio/ogg; codecs=opus",
      "voice": true
    },
    "tags": null,
    "metadata": null
  }
}
```

自动响应语音备忘录的流程在此处读取 `voice`，无需先获取任何内容：一个需要转录录音但转发附件音乐文件的工单队列，仅凭该标志即可完成分支判断。

## 注意事项

- **将 `voice` 视为标记语音备忘录的标志。** 其他任何值（包括字段缺失）均表示普通音频附件。
- **不会报告时长。** 该分支不携带时长信息，如果队列需要时长，请在获取文件后从文件中读取。

## 后续步骤

- [接收消息的工作原理](/docs/guides/whatsapp/receiving-whatsapp)：入站信封、媒体获取以及 `whatsapp.received` webhook
- [WhatsApp 音频消息](/docs/guides/whatsapp/message-types/audio)：同一分支的发送端
- [接收视频](/docs/guides/whatsapp/receiving-whatsapp/video)：视频片段，带有音频分支所没有的字幕
- [WhatsApp 事件](/docs/guides/whatsapp/events)：完整事件列表，通过 API 或 webhooks 获取

## 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)