# WhatsApp 视频消息

视频消息包含一个公共 URL，WhatsApp 在发送时获取该 URL，下方可附带可选标题。

## 发送视频

设置 `video.url`：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  video: { url: "https://cdn.example.com/unboxing.mp4" },
});
console.log(msg.id, msg.status);
```

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

完整结构添加了一个可选的 `caption`：

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "video": {
    "url": "https://cdn.example.com/unboxing.mp4",
    "caption": "How to set it up"
  }
}
```

`video` 没有 `filename` 字段。`from` 在每条服务消息中都是必填的：必须是你的工作区拥有的号码，而不是 Bird 托管的号码。

## 限制

| 字段      | 限制                                    | 执行方                        |
| --------- | --------------------------------------- | ----------------------------- |
| 文件大小  | 16 MB                                   | 仅 WhatsApp，在获取时（异步） |
| 格式      | MP4 容器、H.264 视频、AAC 音频          | 仅 WhatsApp，在获取时（异步） |
| `caption` | 最多 1024 个字符                        | Bird，在接受时（`422`）       |
| `url`     | 绝对路径、`https`、包含主机、无原始空格 | Bird，在接受时（`422`）       |

Bird 会在任何内容入队之前检查 URL 的格式和标题的长度。它不会检查文件的实际大小、容器或编解码器；只有 WhatsApp 在发送时的获取操作才能检查。请参阅中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)和[媒体失败时](/docs/guides/whatsapp/message-types#when-media-fails)。

## 读取入站视频

入站视频携带相同的 `video` 对象，另外还有一个 `id` 和 `mime_type`，这些是 Bird 通过获取文件得到的。在出站回读中这两者都不存在，因为 Bird 从未获取过它发送的文件。请参阅[接收 WhatsApp 视频](/docs/guides/whatsapp/receiving-whatsapp/video)了解完整的入站读取、`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)了解 `media_rejected` 和失败仍计费的事实。视频被 WhatsApp 拒绝时的具体文本尚未像图片那样被独立验证过，因此请将该映射视为基于对称性推断的，而非逐项确认的。
- **WhatsApp 会缓存已获取的 URL 约 10 分钟。** 在该窗口内重新发送相同的 URL 会复用首次获取的结果；更改 URL 以强制重新获取。
- **动画 GIF 不是一种独立类型。** WhatsApp 没有 `gif` 消息类型；你发送的动画 GIF 会以普通 `video`（MP4 MIME 类型）的形式送达收件人，入站返回给你时也是如此。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口以及所有服务消息共享的模型
- [图片](/docs/guides/whatsapp/message-types/images)：用于照片或图形的相同结构
- [音频](/docs/guides/whatsapp/message-types/audio)：用于语音备忘录或音频片段
- [发送 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)