# Recebendo localizações WhatsApp

Um pin que um contato compartilha chega como uma mensagem recebida carregando `location`. O mesmo braço responde a uma [solicitação de localização](/docs/guides/whatsapp/message-types/interactive/location-requests) que você enviou, que é o único tipo interativo cuja resposta chega aqui em vez de em `interactive_reply`.

## O que uma localização recebida carrega

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

| Campo       | O que carrega                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `latitude`  | Latitude em graus decimais                                                                                   |
| `longitude` | Longitude em graus decimais                                                                                  |
| `name`      | O nome do lugar; ausente quando o contato compartilhou um pin simples                                        |
| `address`   | O endereço, que WhatsApp envia apenas junto com um `name`                                                    |
| `url`       | Um link para o lugar, principalmente em uma localização comercial, quando o cliente do remetente forneceu um |

Um pin simples colocado no mapa carrega apenas as duas coordenadas e nada mais, então trate `name`, `address` e `url` como decoração que você exibe quando presente, e não como campos para usar como chave. Leia as coordenadas como números JSON e espere valores negativos nos hemisférios sul e oeste.

## Uma localização que responde a uma solicitação de localização

Quando o pin responde a uma solicitação de localização que você enviou, WhatsApp reporta a solicitação como alvo da resposta e `in_reply_to_message_id` identifica a mensagem que carregou o botão. É isso que liga uma resposta a uma pergunta, e é a diferença em relação a uma [solicitação de informações de contato](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), cuja resposta não carrega esse vínculo.

Nada mais marca o pin como uma resposta. Um contato que compartilha sua localização espontaneamente produz o mesmo braço sem `in_reply_to_message_id`, então uma integração que espera uma resposta verifica esse campo em vez do braço. O campo não é garantia na direção oposta: WhatsApp não marca toda resposta, e a resolução pode falhar, então uma resposta genuína pode chegar sem ele. A seção de [respostas citadas](/docs/guides/whatsapp/receiving-whatsapp#quoted-replies) do hub cobre quando isso acontece e o que fazer onde a classificação precisa se manter.

## O payload do webhook

`whatsapp.received` carrega o braço `location` no envelope do evento:

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

## Pontos de atenção

- **Compartilhamento de localização em tempo real não é modelado como conteúdo.** O que chega é uma localização fixa em um momento, então uma visualização de rastreamento não tem o que atualizar. Não construa uma com base nesse campo.
- **Uma integração que monitora apenas `interactive_reply` não captura isso.** A resposta de uma solicitação de localização chega aqui, e a resposta de uma solicitação de informações de contato chega em `contact_cards`, então um handler que lê apenas toques perde ambas.
- **As coordenadas são o que o dispositivo do contato reportou.** Elas não incluem raio de precisão nem altitude, e um pin que o contato arrastou está onde ele o arrastou. Confirme o endereço por escrito quando ele precisa estar correto.

## Próximos passos

- [Como o recebimento funciona](/docs/guides/whatsapp/receiving-whatsapp): o envelope de entrada, busca de mídia e o webhook `whatsapp.received`
- [Mensagens de localização WhatsApp](/docs/guides/whatsapp/message-types/location): o lado de envio do mesmo braço
- [Solicitações de localização WhatsApp](/docs/guides/whatsapp/message-types/interactive/location-requests): o botão que solicita um pin
- [Eventos WhatsApp](/docs/guides/whatsapp/events): a lista completa de eventos, via API ou webhooks

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