# 接收 WhatsApp 视频

联系人录制或附加的视频片段以入站消息的形式到达，携带 `video`：与所有入站媒体分支使用的相同媒体引用，以及他们在视频下方输入的标题文字（如有）。

## 入站视频携带的内容

```json
{
  "id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "video": {
    "id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
    "mime_type": "video/mp4",
    "caption": "The rattle starts around 0:12"
  },
  "created_at": "2026-08-25T09:11:48Z"
}
```

| 字段        | 携带的内容                                        |
| ----------- | ------------------------------------------------- |
| `id`        | 存储的文件，获取字节时作为 `media_id` 传入        |
| `url`       | 一个 Bird URL，使用你的 API 密钥获取              |
| `mime_type` | WhatsApp 为该片段报告的媒体类型，例如 `video/mp4` |
| `caption`   | 联系人在视频下方输入的文字；未输入时不存在        |

该分支不携带时长、尺寸和缩略图。获取字节后从文件本身读取这些信息，或通过你自己的媒体处理管线获取。

`id` 和 `mime_type` 仅出现在入站视频上，因为 Bird 通过获取文件来获得这两项信息。出站视频回读时携带你提供的 `url`，且没有 `id`。

## 获取字节

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

视频是联系人可能发给你的最大内容，且获取操作直接从存储提供字节而不经过 API，因此请将响应以流的方式写入磁盘或你自己的存储桶，而不是缓冲在内存中。消息及其媒体在消息到达 30 天后一起过期；中心的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)拥有该时间窗口的定义，以及过期后读取返回的内容。

## Webhook 载荷

`whatsapp.received` 在事件信封上携带 `video` 分支：

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:11:48.204Z",
  "data": {
    "whatsapp_id": "wam_01kyc5r9pewu7s3j6m0xyd5qgb",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "video": {
      "id": "waf_01kyc4n5yr8xit1e9o4qsw7ufa",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyc5r9pewu7s3j6m0xyd5qgb/media/waf_01kyc4n5yr8xit1e9o4qsw7ufa",
      "mime_type": "video/mp4",
      "caption": "The rattle starts around 0:12"
    },
    "tags": null,
    "metadata": null
  }
}
```

从排队的 worker 中获取视频片段，而不是在 webhook 处理程序内部获取：端点需要快速响应，而媒体在整个保留窗口期间都可用。

## 注意事项

- **视频笔记按视频读取。** WhatsApp 的圆形视频笔记到达此分支时没有区分标志，与音频不同，音频中语音笔记会设置 `voice`。
- **每条消息一个片段。** 多个视频以多条入站消息到达，每条都有自己的媒体引用。

## 后续步骤

- [接收的工作原理](/docs/guides/whatsapp/receiving-whatsapp)：入站信封、媒体获取以及 `whatsapp.received` webhook
- [WhatsApp 视频消息](/docs/guides/whatsapp/message-types/video)：同一分支的发送端
- [接收音频](/docs/guides/whatsapp/receiving-whatsapp/audio)：语音笔记和附加的音频文件
- [WhatsApp 事件](/docs/guides/whatsapp/events)：完整的事件列表，通过 API 或 webhook 获取

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