WhatsApp 位置请求

位置请求会在 WhatsApp 消息下方放置一个按钮，请求收件人分享其当前位置。当你需要实时位置（例如上车点）而非已保存的地址时使用它。如果需要的是电话号码，请使用联系人信息请求。

发送位置请求

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

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);

msg = client.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.",
    },
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:   "+16505551234",
		From: "+13124495648",
		Interactive: &bird.WhatsAppInteractiveSend{
			Type:     "location_request_message",
			BodyText: "Let's start with your pickup. Share your current location, or type an address instead.",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('location_request_message')
    ->setBodyText("Let's start with your pickup. Share your current location, or type an address instead.");

$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13124495648 \
  --interactive "{\"body_text\":\"Let's start with your pickup. Share your current location, or type an address instead.\",\"type\":\"location_request_message\"}" \
  --to +16505551234

{
  "name": "whatsapp_send",
  "arguments": {
    "from": "+13124495648",
    "interactive": {
      "body_text": "Let's start with your pickup. Share your current location, or type an address instead.",
      "type": "location_request_message"
    },
    "to": "+16505551234"
  }
}

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
    }
  }'

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

in_reply_to_message_id 在此类型上仍然有效，用于引用同一对话中的早期消息。请参阅 hub 的引用消息以关联回复，了解解析的工作方式及可能遗漏的情况。

读取分享的位置

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

代码示例

{
  "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 的读取回复。

将回答与问题关联

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

代码示例

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

请参阅引用消息以关联回复，了解解析的工作方式及未命中的情况。

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

注意事项

客户服务窗口必须处于开启状态。 位置请求是一条服务消息，只有在窗口开启时才能送达；请参阅 hub 的客户服务窗口。窗口检查采用开放式失败策略，因此 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，当 id 指定的消息无法被引用时返回 422 E15072。请参阅 hub 的错误获取完整的交互式错误表，以及发送 WhatsApp 消息了解任何 WhatsApp 发送可能遇到的错误。

后续步骤

WhatsApp 交互式消息：六种交互类型的共同点
联系人信息请求：请求电话号码而非位置
发送 WhatsApp 消息：请求信封、202 模型和安全重试