# WhatsApp 位置请求

位置请求会在 WhatsApp 消息下方放置一个按钮，请求收件人分享其当前位置。当你需要实时位置（例如上车点）而非已保存的地址时使用它。如果需要的是电话号码，请使用[联系人信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)。

## 发送位置请求

将 `interactive.type` 设置为 `location_request_message`，附带一个 `body_text`，不含其他内容。WhatsApp 会自行渲染按钮，因此无需为其添加标签：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "location_request_message",
    body_text:
      "Let's start with your pickup. Share your current location, or type an address instead.",
  },
});
console.log(msg.id, msg.status);
```

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

`from` 在每条服务消息中都是必需的：必须是你的工作区拥有的号码，而非 Bird 托管的号码。此类型没有自己的专属字段，且 schema 明确禁止 `header`、`footer_text` 以及所有其他类型的字段（`buttons`、`list`、`cta_url`、`cards`），因此 `body_text` 就是整条消息，上限为 1024 个字符。

`in_reply_to_message_id` 在此类型上仍然有效，用于引用同一对话中的早期消息。请参阅 hub 的[引用消息以关联回复](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply)，了解解析的工作方式及可能遗漏的情况。

## 读取分享的位置

点击不会产生 `interactive_reply`。它会作为普通入站 `location` 消息到达，与联系人主动分享位置时产生的消息格式相同，因此已经读取入站位置的集成无需为此类型添加新分支：

```json
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "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:04:11Z"
}
```

`location` 的所有字段都不是必需的：`latitude` 和 `longitude` 通常同时存在，但当收件人分享的是纯图钉时 `name` 不存在，`address` 仅在 `name` 也被设置时才出现，`url` 仅在收件人客户端恰好提供了商户位置时才出现。请防御性编码，不要假设街道地址一定会随图钉一起返回。你可以通过消息列表或 `GET /v1/whatsapp/messages/{id}` 查看此回复；完整路径请参阅 hub 的[读取回复](/docs/guides/whatsapp/message-types/interactive#reading-a-reply)。

## 将回答与问题关联

Meta 会在此类型的回复上设置一个 `context`，指向它所回答的请求，因此入站消息携带 `in_reply_to_message_id`，你无需自己设计关联方案：

```json
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
```

请参阅[引用消息以关联回复](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply)，了解解析的工作方式及未命中的情况。

这与[联系人信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)形成了刻意的对比：该类型的回复完全不携带 `context`，因此其 `in_reply_to_message_id` 永远无法解析，关联只能依赖 `from` 加时间推断。位置请求的回复可以解析，因此 `in_reply_to_message_id` 是将分享的位置关联回发起请求的可靠方式。

## 注意事项

- **客户服务窗口必须处于开启状态。** 位置请求是一条服务消息，只有在窗口开启时才能送达；请参阅 hub 的[客户服务窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。窗口检查采用开放式失败策略，因此 `202` 并不能证明发送时窗口确实处于开启状态。
- **`from` 必须是你的工作区拥有的号码。** 省略该字段或指定一个未连接的发送号码，会在创建发送之前被拒绝。
- **不保证一定会收到回复。** 收件人可以关闭位置分享界面、完全忽略消息，或以自由文本输入地址，后者会作为不携带 `location` 的普通入站文本消息到达。Meta 未记录任何关于拒绝或关闭分享的信号，因此请将该请求视为即发即弃，在你自己一侧设置超时，而非等待可能永远不会到来的响应。
- **分享的图钉可能只包含坐标。** 收件人的客户端决定是否附带名称和地址；纯图钉两者都没有，因此不要假设它们会一起出现。
- **无请求头、无页脚、无专属字段。** schema 明确禁止在此类型上使用 `header` 和 `footer_text`，也没有字段用于标注按钮。你需要的任何附加说明都必须放在 `body_text` 内。
- **回复是一条 `location` 消息，而非 `interactive_reply`。** 仅监听 `interactive_reply` 来捕获点击的集成会完全遗漏此类型；请改为监听入站 `location`。

schema 能在此处表达的所有违规情况，包括过长的 `body_text`、`header`、`footer_text`，或 `buttons`、`list`、`cta_url`、`cards` 中的任何一个，都是无目录代码的普通请求验证失败。无法解析的引用会在创建或计费之前使请求失败：当 id 指定的消息不属于此工作区时返回 `404` [`E15071`](/docs/api/errors/E15071)，当 id 指定的消息无法被引用时返回 `422` [`E15072`](/docs/api/errors/E15072)。请参阅 hub 的[错误](/docs/guides/whatsapp/message-types/interactive#errors)获取完整的交互式错误表，以及[发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)了解任何 WhatsApp 发送可能遇到的错误。

## 后续步骤

- [WhatsApp 交互式消息](/docs/guides/whatsapp/message-types/interactive)：六种交互类型的共同点
- [联系人信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)：请求电话号码而非位置
- [发送 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)