Sign inGet started

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.

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:
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);
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 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:
Exemplo de código
{
  "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 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:
Exemplo de código
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Consulte citar uma mensagem para correlacionar uma resposta para saber como essa resolução funciona e como é quando falha.
Esse é o contraste intencional com solicitações de informações de contato: 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. 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 quando o id não nomeia nenhuma mensagem que esse espaço de trabalho possui, 422 E15072 quando nomeia uma que não pode ser citada. Consulte no hub erros para a tabela interativa completa de erros e Enviando mensagens WhatsApp para os erros que qualquer envio WhatsApp pode encontrar.

Próximos passos