# Solicitações de localização no WhatsApp

Uma solicitação de localização exibe um botão abaixo de uma mensagem do WhatsApp pedindo ao destinatário para compartilhar onde está. Use quando você precisa de uma posição atual, como um ponto de embarque, em vez de um endereço salvo. Para solicitar um número de telefone, use [solicitações de informações de contato](/docs/guides/whatsapp/message-types/interactive/contact-info-requests).

## Enviar uma solicitação de localização

Defina `interactive.type` como `location_request_message`, com um `body_text` e nada mais. WhatsApp renderiza o próprio botão, então não há nada para rotulá-lo:

**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](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/message-types/interactive/location-requests.curl.md)

`from` é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado pelo Bird. Esse tipo não nomeia nenhum campo próprio, e o schema proíbe `header`, `footer_text` e todos os campos de outros tipos (`buttons`, `list`, `cta_url`, `cards`), então `body_text` é a mensagem inteira, limitada a 1024 caracteres.

`in_reply_to_message_id` ainda funciona nesse tipo, para citar uma mensagem anterior na mesma conversa. Consulte no hub [citar uma mensagem para correlacionar uma resposta](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) para saber como a resolução funciona e o que ela pode perder.

## Lendo a localização compartilhada

Um toque não produz um `interactive_reply`. Ele chega como uma mensagem de entrada `location` comum, no mesmo formato que um contato compartilhando sua localização espontaneamente produziria, então uma integração que já lê localizações de entrada não precisa de uma nova ramificação para esse tipo:

```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"
}
```

Nenhum dos campos de `location` é obrigatório: `latitude` e `longitude` geralmente estão ambos presentes, mas `name` fica ausente quando o destinatário compartilhou apenas um pin, `address` só aparece quando `name` também está definido, e `url` aparece apenas em localizações comerciais que o cliente do destinatário incluiu. Programe defensivamente em vez de assumir que um endereço vem junto com o pin. Você vê essa resposta pela lista de mensagens ou por `GET /v1/whatsapp/messages/{id}`; consulte no hub [lendo uma resposta](/docs/guides/whatsapp/message-types/interactive#reading-a-reply) para o caminho completo.

## Correlacionando a resposta com a pergunta

A Meta define um `context` na resposta desse tipo nomeando a solicitação que ele responde, então a mensagem de entrada carrega `in_reply_to_message_id` e você não precisa de nenhum esquema próprio de correlação:

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

Consulte [citar uma mensagem para correlacionar uma resposta](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) para saber como essa resolução funciona e como é quando falha.

Esse é o contraste intencional com [solicitações de informações de contato](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): a resposta desse tipo não carrega nenhum `context`, então seu `in_reply_to_message_id` nunca resolve e a correlação recai sobre `from` mais timing. A resposta de uma solicitação de localização resolve, então `in_reply_to_message_id` é a forma confiável de vincular a localização compartilhada à solicitação que a pediu.

## Pontos de atenção

- **A janela de atendimento ao cliente precisa estar aberta.** Uma solicitação de localização é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; consulte no hub [janela de atendimento ao cliente](/docs/guides/whatsapp/message-types#the-customer-service-window). A verificação da janela falha de forma permissiva, então um `202` não é prova de que a janela estava de fato aberta quando o envio é feito.
- **`from` precisa ser um número que o seu espaço de trabalho possui.** Omiti-lo, ou informar um número que não é um remetente conectado, é rejeitado antes de o envio ser criado.
- **Nenhuma resposta é garantida.** O destinatário pode fechar a tela de compartilhamento de localização, ignorar a mensagem completamente ou digitar um endereço como texto livre, que chega como uma mensagem de texto de entrada comum sem nenhum `location`. A Meta não documenta nenhum sinal para um compartilhamento recusado ou dispensado, então trate a solicitação como disparar-e-esquecer e defina um timeout do seu lado em vez de esperar por uma resposta que pode nunca chegar.
- **Um pin compartilhado pode conter apenas coordenadas.** O cliente do destinatário decide se anexa nome e endereço; um pin simples não tem nenhum dos dois, então não assuma que um vem junto com o outro.
- **Sem header, sem footer e sem campo próprio.** O schema proíbe `header` e `footer_text` nesse tipo, e não há campo para rotular o botão. Qualquer texto adicional que você precise deve ir dentro de `body_text`.
- **A resposta é uma mensagem `location`, não um `interactive_reply`.** Uma integração que observa apenas `interactive_reply` para detectar um toque vai perder esse tipo completamente; observe mensagens de entrada `location` em vez disso.

Tudo que o schema pode expressar aqui, um `body_text` longo demais, um `header`, um `footer_text`, ou qualquer um entre `buttons`, `list`, `cta_url`, `cards`, é uma falha simples de validação de solicitação sem código de catálogo. Uma citação que não resolve falha a solicitação antes de qualquer coisa ser criada ou cobrada: `404` [`E15071`](/docs/api/errors/E15071) quando o id não nomeia nenhuma mensagem que esse espaço de trabalho possui, `422` [`E15072`](/docs/api/errors/E15072) quando nomeia uma que não pode ser citada. Consulte no hub [erros](/docs/guides/whatsapp/message-types/interactive#errors) para a tabela interativa completa de erros e [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp) para os erros que qualquer envio WhatsApp pode encontrar.

## Próximos passos

- [Mensagens interativas WhatsApp](/docs/guides/whatsapp/message-types/interactive): o que os seis tipos interativos têm em comum
- [Solicitações de informações de contato](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): solicite um número de telefone em vez de uma localização
- [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): o envelope da solicitação, o modelo de `202` e retentativas seguras

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