# 接收 WhatsApp 消息 入站消息与出站消息使用同一资源，无需轮询单独的收件箱端点。在仪表板中通过[消息列表](/docs/guides/whatsapp/message-log)查看，或通过 API 使用 `GET /v1/whatsapp/messages/{id}` 将列表筛选为入站消息后读取。 每条入站消息都会将[客户服务窗口](/docs/knowledge-base/whatsapp/customer-service-window)延长至该消息自身时间戳之后的 24 小时，这正是您的自由回复能够送达的前提。延迟到达 Bird 的消息仍携带联系人实际授予的窗口，已有的更晚截止时间不会被缩短。 ## 入站消息包含的内容 每条入站消息共享同一个信封：一个 `id`、`direction: "inbound"`、`from` 中的联系人、`to` 中您自己的号码、值为 `received` 的 `status`，以及一个 `created_at`。信封旁边恰好有一个内容字段，标识联系人发送的内容： ```json { "id": "wam_01kya19eknftrs2s6p82asmvnh", "direction": "inbound", "from": { "phone_number": "+14155550100" }, "to": { "phone_number": "+13124495569" }, "status": "received", "text": { "body": "Is my order out for delivery yet?" }, "created_at": "2026-08-25T09:04:11Z" } ``` `from` 根据 WhatsApp 报告的身份标识联系人：一个 E.164 格式的 `phone_number`、一个 `bsuid`，或两者兼有，加上他们公开的 `username` 和 `display_name`。已设置 WhatsApp 用户名的联系人可以在没有电话号码的情况下联系您；参见[业务范围用户 ID](/docs/guides/whatsapp/business-scoped-user-ids)了解应存储什么以及如何请求号码。 这些内容字段中的一个，即一个 **arm**，承载联系人发送的内容，每条消息上恰好设置一个 arm。每个 arm 都有独立的页面，包含读取结构、`whatsapp.received` 载荷以及注意事项： | 字段 | 入站消息包含的内容 | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [`text`](/docs/guides/whatsapp/receiving-whatsapp/plain-text) | `body`，联系人输入的消息 | | [`image`](/docs/guides/whatsapp/receiving-whatsapp/images) | 一个 `id`、`url`、`mime_type`，以及任何 `caption` | | [`video`](/docs/guides/whatsapp/receiving-whatsapp/video) | 相同的媒体字段，加上任何 `caption` | | [`audio`](/docs/guides/whatsapp/receiving-whatsapp/audio) | 相同的媒体字段，语音消息上加 `voice`；无标题字段 | | [`sticker`](/docs/guides/whatsapp/receiving-whatsapp/stickers) | 相同的媒体字段，加上 `animated` | | [`document`](/docs/guides/whatsapp/receiving-whatsapp/documents) | 相同的媒体字段，加上任何 `filename` 和 `caption` | | [`location`](/docs/guides/whatsapp/receiving-whatsapp/location) | `latitude` 和 `longitude`，有时还有 `name`、`address` 或一个 `url` | | [`contact_cards`](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) | 联系人分享的一张或多张联系人卡片 | | [`interactive_reply`](/docs/guides/whatsapp/receiving-whatsapp/interactive-replies) | 联系人点击的按钮或行的 `slug` 和 `text` | | [`unsupported`](/docs/guides/whatsapp/receiving-whatsapp/unsupported) | API 未建模的 WhatsApp 内容类型，例如订单 | 有两种点击到达的 arm 可能出乎意料。[位置请求](/docs/guides/whatsapp/message-types/interactive/location-requests)作为普通的入站 `location` 返回，[联系人信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)作为 `contact_cards` 返回，因此只监听 `interactive_reply` 来捕获点击的集成会遗漏这两者。 ## 获取入站媒体 入站的 `image`、`video`、`audio`、`sticker` 或 `document` 到达时是对 Bird 存储的文件的引用，而非文件本身： ```json { "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?" } } ``` 使用通道的媒体方法获取字节数据，传入消息 id 和媒体 `id`： **TypeScript** ```typescript const media = await bird.whatsapp.messages.media( "wam_01kya19eknftrs2s6p82asmvnh", "waf_01kyb2m4xq7whs0d8n3prv6tez", ); console.log(media.contentType, media.contentLength); ``` Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/receiving-whatsapp.curl.md) 返回的字节数据带有为其声明的 `mime_type` 存储类型。Bird 无法识别的 id 返回 `404`，出站消息没有可提供的已存储媒体。 **消息在到达后 30 天内可回读，其媒体的存续时间不会超过消息本身。** 此端点在提供文件之前先读取消息，因此窗口过期后两者都返回 `404`。如果需要更长时间保留文件，请在消息仍可读时存储。提前结束的唯一情况是存储的字节在窗口到期前被删除：获取时返回 `410` [`E15021`](/docs/api/errors/E15021)，而消息本身仍可回读，带有媒体的 `mime_type` 和 `caption`。 底层实现中，此端点以 `302` 返回一个有效期为 15 分钟的预签名 URL。SDK 和 CLI 会自动处理该跳转。直接调用时，预签名 URL 自带凭证，因此重定向后的请求不得再发送您的 `Authorization` 请求头。同时发送两者会失败。`curl -L` 在跨主机重定向时会自动丢弃该请求头；逐字转发请求头的客户端需要将 `Location` 作为单独的未认证请求获取。 ## 引用回复 当 WhatsApp 将消息标记为回复时，`in_reply_to_message_id` 指明入站消息所回复的那条消息： ```json { "id": "wam_01kyb2m4xq7whs0d8n3prv6tez", "direction": "inbound", "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh", "text": { "body": "Yes, that one" } } ``` WhatsApp 不会标记每条回复，未标记的回复不携带任何 ID。当被引用的消息无法匹配到 Bird 持有的消息时，该字段也会被省略：例如在此工作区开始记录之前发送的消息，或超过 Bird 保留 WhatsApp 自有消息 ID 的 15 天期限的消息。未匹配时省略该字段而非报告一个，这与回复未指向任何消息的情况读取结果相同。 将该字段视为提示而非键。您自己发送时的 `metadata` 在此无用，因为它保留在您的消息上，不会传递到联系人的回复中，因此需要知道答案属于哪个问题的集成应自行跟踪最后向该联系人提出的问题。参见[引用消息](/docs/guides/whatsapp/sending-whatsapp#quoting-a-message)了解出站侧的用法。 ## Webhook 订阅 `whatsapp.received` 以在入站消息到达时立即处理，而非轮询列表。载荷在事件信封之上携带内容，因此端点无需后续读取： ```json { "type": "whatsapp.received", "timestamp": "2026-08-25T09:04:11.118Z", "data": { "whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez", "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b", "direction": "inbound", "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" }, "to": { "phone_number": "+13124495569" }, "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh", "interactive_reply": { "type": "button", "button": { "slug": "cancel-booking", "text": "Cancel" } }, "tags": null, "metadata": null } } ``` 参见 [WhatsApp 事件](/docs/guides/whatsapp/events#webhooks)了解完整的信封和其余事件列表。 ## 后续步骤 - [服务消息](/docs/guides/whatsapp/message-types)：相同内容 arm 的发送侧 - [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：在服务窗口内回复，以及引用消息 - [WhatsApp 事件](/docs/guides/whatsapp/events)：完整的事件列表，通过 API 或 webhook - [WhatsApp 日志](/docs/guides/whatsapp/message-log)：在仪表板中浏览对话 ## 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)