# WhatsApp 位置消息

位置消息发送一个图钉：地图上的一个点，下方可附带可选的名称和地址。本页介绍发送端；如需请求联系人分享其位置，请参阅[位置请求](/docs/guides/whatsapp/message-types/interactive/location-requests)。

## 发送位置

设置 `location.latitude` 和 `location.longitude`：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  location: { latitude: 37.7793, longitude: -122.4193 },
});
console.log(msg.id, msg.status);
```

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

完整结构还包含 `name` 和 `address`：

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Ferry Building Pickup",
    "address": "1 Market St, San Francisco, CA 94105"
  }
}
```

`address` 仅在同时设置了 `name` 时才会向接收者显示。每条服务消息都必须包含 `from`：一个您的工作区拥有的号码，而非 Bird 托管的号码。

## 限制

| 字段        | 约束                                             | 执行方                   |
| ----------- | ------------------------------------------------ | ------------------------ |
| `latitude`  | 必填，-90 至 90，十进制度                        | Bird，接受时校验 (`422`) |
| `longitude` | 必填，-180 至 180，十进制度                      | Bird，接受时校验 (`422`) |
| `name`      | 可选，最多 1000 个字符                           | Bird，接受时校验 (`422`) |
| `address`   | 可选，最多 1000 个字符，仅在设置了 `name` 时显示 | Bird，接受时校验 (`422`) |

WhatsApp 自身的文档将 `latitude` 和 `longitude` 列为必填，但未说明数值范围；±90/±180 的范围校验以及 `name` 和 `address` 的 1000 字符上限是 Bird 自身的约束。

## 读取入站位置

联系人主动分享其位置或回复位置请求时，会产生一条普通的入站 `location` 消息。消息内容不保证完整：原始图钉可能不包含 `name` 和 `address`，入站消息还可能携带一个指向该地点的 `url`，而您发送的位置消息中不会出现该字段。位置不是媒体类型，因此没有文件可供获取。请参阅[接收 WhatsApp 位置](/docs/guides/whatsapp/receiving-whatsapp/location)了解完整的入站读取、`whatsapp.received` 载荷以及注意事项。

## 限制与边界情况

- **客服窗口必须处于开启状态。** 位置发送属于服务消息，只有在窗口开启期间才能送达；请参阅中心的[客服窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。
- **`name` 和 `address` 在读取时是真正可选的，而非带有回退值的可选。** 原始图钉二者都没有，且 `address` 不会在没有 `name` 的情况下出现。不要假设坐标一定附带街道地址。
- **这与位置请求不是同一类型。**[位置请求](/docs/guides/whatsapp/message-types/interactive/location-requests)是一种交互类型，用于向接收者请求其位置；本页是向他们发送位置。不要混淆这两种发送结构。
- **点击位置请求后返回的是普通的入站 `location` 消息，而非 `interactive_reply`。** 仅监听 `interactive_reply` 来捕获点击的集成会完全遗漏此消息；还必须监听入站 `location`。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客服窗口及所有服务消息共享的模型
- [位置请求](/docs/guides/whatsapp/message-types/interactive/location-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)