# 接收 WhatsApp 图片

联系人发送的照片或图形会作为入站消息到达，携带 `image`：一个指向 Bird 为您存储的文件的引用，以及他们在图片下方输入的说明文字。

## 入站图片携带的内容

```json
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "image": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "image/jpeg",
    "caption": "Is this the right part?"
  },
  "created_at": "2026-08-25T09:04:11Z"
}
```

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

`id` 和 `mime_type` 仅出现在入站图片上：Bird 通过获取文件得到这两个值，且从不存储您发送的那个。出站图片读回时只有您提供的 `url`，没有 `id`。

将 `mime_type` 视为 WhatsApp 的报告而非保证，并基于它而不是 `url` 中的文件扩展名来分支判断，因为后者不携带扩展名。

## 获取文件字节

`url` 和 `id` 都指向同一个存储文件：将消息 ID 和媒体 `id` 传给频道的媒体方法，可以在任何 SDK、CLI 或 cURL 中调用。Hub 的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)包含每种语言的调用示例，以及它遵循的重定向和请求头规则。

消息及其媒体一起过期，在消息到达后 30 天失效；Hub 的[获取入站媒体](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media)管理该时间窗口以及过期后读取返回的内容。在消息仍可读取时，将您需要长期保留的图片存储下来。

## Webhook 载荷

`whatsapp.received` 在事件信封上携带 `image` 分支，包括媒体引用在内：

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "image": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "image/jpeg",
      "caption": "Is this the right part?"
    },
    "tags": null,
    "metadata": null
  }
}
```

Webhook 在消息到达时触发，也是保留窗口开始的时间，因此将获取操作排队而非内联执行的端点拥有整个窗口来完成处理。

## 注意事项

- **说明文字属于联系人。** 它以纯文本形式到达，不包含格式或实体信息，因此请将其作为文本渲染。
- **每条消息一张图片。** 联系人发送多张照片会产生多条入站消息，每条都有自己的 `id` 和媒体引用。按 `from` 和到达时间对它们进行分组；没有数组将它们聚合在一起。

## 后续步骤

- [接收的工作原理](/docs/guides/whatsapp/receiving-whatsapp)：入站信封、媒体获取和 `whatsapp.received` webhook
- [WhatsApp 图片消息](/docs/guides/whatsapp/message-types/images)：同一分支的发送端
- [接收文档](/docs/guides/whatsapp/receiving-whatsapp/documents)：相同的媒体结构，附带发送者的文件名
- [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)