接收 WhatsApp 图片

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

入站图片携带的内容

代码示例

{
  "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 的获取入站媒体包含每种语言的调用示例，以及它遵循的重定向和请求头规则。

消息及其媒体一起过期，在消息到达后 30 天失效；Hub 的获取入站媒体管理该时间窗口以及过期后读取返回的内容。在消息仍可读取时，将您需要长期保留的图片存储下来。

Webhook 载荷

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

代码示例

{
  "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 和到达时间对它们进行分组；没有数组将它们聚合在一起。

后续步骤

接收的工作原理：入站信封、媒体获取和 whatsapp.received webhook
WhatsApp 图片消息：同一分支的发送端
接收文档：相同的媒体结构，附带发送者的文件名
WhatsApp 事件：完整的事件列表，通过 API 或 webhook 获取