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

Exemplo de código

{
  "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, 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 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:

Exemplo de código

{
  "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: o envelope de entrada, busca de mídia e o webhook whatsapp.received
Mensagens de localização WhatsApp: o lado de envio do mesmo braço
Solicitações de localização WhatsApp: o botão que solicita um pin
Eventos WhatsApp: a lista completa de eventos, via API ou webhooks

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação