# 接收 WhatsApp 位置消息

联系人分享的图钉以携带 `location` 的入站消息到达。同一分支也用于回复你发送的[位置请求](/docs/guides/whatsapp/message-types/interactive/location-requests)，这是唯一一种回复落在此处而非 `interactive_reply` 上的交互类型。

## 入站位置消息包含什么

```json
{
  "id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Embarcadero Plaza",
    "address": "1 Market St, San Francisco, CA 94105"
  },
  "created_at": "2026-08-25T09:23:14Z"
}
```

| 字段        | 包含内容                                                                 |
| ----------- | ------------------------------------------------------------------------ |
| `latitude`  | 十进制度数表示的纬度                                                     |
| `longitude` | 十进制度数表示的经度                                                     |
| `name`      | 地点名称；联系人分享的是纯图钉时不存在                                   |
| `address`   | 街道地址，WhatsApp 仅在有 `name` 时才发送                                |
| `url`       | 指向该地点的链接，主要出现在商家位置上，前提是发送方的客户端提供了该链接 |

在地图上放置的纯图钉只携带两个坐标，没有其他内容，因此请将 `name`、`address` 和 `url` 视为存在时展示的附加信息，而非用于查找的关键字段。将坐标作为 JSON 数字读取，南半球和西半球的值为负数。

## 回复位置请求的位置消息

当图钉回复你发送的位置请求时，WhatsApp 将该请求报告为回复的目标，`in_reply_to_message_id` 指出携带按钮的消息。这就是将答案与问题关联起来的方式，也是与[联系人信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)的区别，后者的回复不携带此类链接。

没有其他标记表明该图钉是一个回答。联系人主动分享位置时会产生相同的分支但不含 `in_reply_to_message_id`，因此监听回答的集成应检查该字段而非分支本身。该字段在反方向上也不是保证：WhatsApp 并非标记每个回复，解析可能会遗漏，因此真正的回答也可能不带该字段到达。Hub 的[引用回复](/docs/guides/whatsapp/receiving-whatsapp#quoted-replies)说明了这种情况何时发生以及在分类必须成立时该怎么做。

## Webhook 载荷

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

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:23:14.507Z",
  "data": {
    "whatsapp_id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "location": {
      "latitude": 37.7793,
      "longitude": -122.4193,
      "name": "Embarcadero Plaza",
      "address": "1 Market St, San Francisco, CA 94105"
    },
    "tags": null,
    "metadata": null
  }
}
```

## 注意事项

- **实时位置共享不作为内容建模。** 到达的是固定在某一时刻的单个位置，跟踪视图没有可更新的数据来源。不要基于此字段构建跟踪功能。
- **仅监听 `interactive_reply` 的集成会遗漏此消息。** 位置请求的回答到达此处，联系人信息请求的回答到达 `contact_cards`，因此只读取点击事件的处理程序会丢失两者。
- **坐标是联系人设备上报的值。** 它们不包含精度半径和海拔，联系人拖动的图钉就在他们拖到的位置。在地址必须准确时，用文字确认地址。

## 后续步骤

- [接收消息的工作原理](/docs/guides/whatsapp/receiving-whatsapp)：入站信封、媒体拉取和 `whatsapp.received` webhook
- [WhatsApp 位置消息](/docs/guides/whatsapp/message-types/location)：同一分支的发送端
- [WhatsApp 位置请求](/docs/guides/whatsapp/message-types/interactive/location-requests)：用于请求图钉的按钮
- [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)