Localização no WhatsApp pela API: enviar, pedir e compartilhar em tempo real

Pela API não oficial do WhatsApp você resolve localização em três direções: envia um pin com POST /{key}/message/location, pede a posição do cliente com um botão nativo em POST /{key}/message/location-request e compartilha localização ao vivo com POST /{key}/message/live-location. É o que transforma "me manda o endereço certinho?" em um toque — para delivery, visita técnica, retirada em loja e qualquer operação que depende de onde as pessoas estão.

Endereço digitado à mão é fonte clássica de erro: número trocado, bairro errado, "é a casa do portão azul". Coordenadas não erram. Neste guia você vê os três endpoints, um fluxo completo de entrega e os cuidados para usar localização sem invadir ninguém.

A camada não oficial da WAME é independente e não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Os três jeitos de usar localização

Todos seguem o mesmo padrão da API: POST para https://us.api-wa.me/{key}/..., Content-Type: application/json e o destinatário em to (telefone com DDI, grupo terminado em @g.us ou LID).

Enviar uma localização fixa

É o pin clássico: o cliente vê um mapa, o nome do lugar e o endereço, e toca para abrir no app de mapas.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/location" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "location": {
      "latitude": -23.5874,
      "longitude": -46.6576,
      "name": "Loja Vila Mariana",
      "address": "Rua Domingos de Morais, 1000 - Vila Mariana, São Paulo - SP"
    }
  }'

Só latitude e longitude são obrigatórios, mas preencha name e address: é o que o cliente lê antes de abrir o mapa, e evita a pergunta "é aquela loja da esquina?".

Onde isso aparece no dia a dia:

• Resposta automática a "onde vocês ficam?" — o bot detecta a pergunta e responde com o pin, não com um texto de endereço.
• Confirmação de agendamento — "Seu horário é amanhã às 14h, aqui" + localização da clínica.
• Ponto de retirada — pedido pronto, pin do balcão de retirada.
• Eventos — combine com convite de evento pela API para mandar data e lugar juntos.

Se você tem várias unidades, a mesma chamada resolve "qual a loja mais perto?": pergunte o bairro ou peça a localização (próxima seção), calcule a unidade mais próxima e envie o pin dela.

Pedir a localização do cliente com um botão

Este é o recurso que mais economiza atendimento. Em vez de pedir o endereço por texto, você envia um pedido nativo: o cliente vê sua mensagem com um botão para compartilhar a localização e só precisa tocar.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/location-request" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Para calcular o frete certinho, toque no botão e compartilhe sua localização 📍"
  }'

O text é obrigatório e deve dizer por que você está pedindo. Pedido de localização sem contexto assusta; com motivo claro ("calcular o frete", "mandar o técnico certo"), é serviço.

Um detalhe que vale para qualquer mensagem interativa: se a conversa ainda está fria — o cliente nunca falou com o número —, abra com um texto antes do pedido. No fluxo normal de delivery isso nem aparece, porque é o cliente que chama primeiro. O porquê está em como aquecer um número.

Receber a localização no webhook

Quando o cliente compartilha, a posição chega no mesmo webhook das mensagens, no envelope meta, como uma mensagem de tipo localização com as coordenadas. Os nomes exatos dos campos estão na documentação; o importante é isolar a leitura numa função, como fizemos no bot do zero:

function extrairLocalizacao(body) {
  const msg = body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!msg || msg.type !== 'location') return null;

  // Ajuste os campos conforme o formato descrito em /docs.
  const loc = msg.location;
  return {
    de: msg.from,
    lat: loc?.latitude,
    lng: loc?.longitude,
    messageId: msg.id,
  };
}

Com a coordenada em mãos, o resto é lógica sua:

// Distância em km entre dois pontos (fórmula de haversine)
function distanciaKm(a, b) {
  const R = 6371;
  const rad = (g) => (g * Math.PI) / 180;
  const dLat = rad(b.lat - a.lat);
  const dLng = rad(b.lng - a.lng);
  const h =
    Math.sin(dLat / 2) ** 2 +
    Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLng / 2) ** 2;
  return 2 * R * Math.asin(Math.sqrt(h));
}

const LOJA = { lat: -23.5874, lng: -46.6576 };
const km = distanciaKm(LOJA, { lat: loc.lat, lng: loc.lng });
const frete = km <= 3 ? 'grátis' : `R$ ${(km * 1.5).toFixed(2)}`; // sua regra

A distância em linha reta é uma aproximação; se o frete precisa da distância de rota, passe as coordenadas para o serviço de mapas que você já usa. O ganho continua o mesmo: nada de endereço digitado errado.

Compartilhar localização em tempo real

A localização ao vivo é o "acompanhe seu pedido" dentro do WhatsApp. Você envia uma posição que o app do cliente mostra como localização em tempo real:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/live-location" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "caption": "Seu pedido saiu! O entregador está a caminho 🛵"
  }'

Casos em que ela vale a pena:

• Entrega — o cliente para de mandar "já saiu?" a cada cinco minutos.
• Visita técnica — "o técnico está a 10 minutos" com o mapa junto evita cliente fora de casa.
• Transporte e traslado — motorista chegando ao ponto de encontro.

Cuidado de privacidade: a localização ao vivo é de quem está se deslocando — o entregador, o técnico. Combine isso com a equipe, deixe claro quando o compartilhamento começa e termina, e não use para monitorar funcionário fora do serviço.

Um fluxo completo de delivery

Juntando as peças, um atendimento de delivery fica assim:

1. Cliente chama — "quero pedir".
2. Bot responde e pede a localização com location-request, explicando que é para o frete.
3. Webhook recebe as coordenadas; o sistema calcula distância, frete e unidade mais próxima.
4. Bot confirma o pedido com valor e prazo (texto ou botões — a conversa já está quente).
5. Pedido sai: live-location com a legenda "saiu para entrega".
6. Entregue: mensagem de confirmação e, se fizer sentido, uma pesquisa de satisfação.

Tudo isso acontece numa conversa que o cliente iniciou. É o uso mais seguro possível da API não oficial: o volume acompanha os pedidos reais, as mensagens são esperadas e ninguém denuncia a pizzaria que avisou que a pizza saiu. É por isso que, nesse tipo de operação, a taxa de bloqueio é muito baixa para quem usa do jeito certo. Os fundamentos estão em o que derruba um número.

Boas práticas com localização

• Sempre explique o motivo ao pedir a localização. Pedido sem contexto parece golpe.
• Não guarde mais do que precisa. Coordenada de entrega é dado pessoal; guarde vinculada ao pedido, pelo tempo necessário, e siga a sua política de privacidade. O contrato com cliente e a LGPD estão em API de WhatsApp e LGPD.
• Tenha fallback em texto. Nem todo cliente compartilha — aceite o endereço digitado e siga o fluxo.
• Nada de pedido em massa. Mandar pedido de localização para uma lista de quem não está comprando nada é abordagem não solicitada. A WAME não apoia esse uso, e ele derruba número rápido.
• Grupos também recebem pin. Para um evento ou uma turma, mandar a localização no grupo (to com @g.us) economiza dezenas de "onde é?".

Conclusão

Localização é um daqueles recursos pequenos que resolvem um problema grande: endereço errado, cliente perguntando onde fica, entrega sem visibilidade. Com a API não oficial da WAME você envia o pin da loja com message/location, pede a posição do cliente com um toque via message/location-request e deixa ele acompanhar a entrega com message/live-location — tudo no mesmo padrão de chamada, dentro da conversa que o próprio cliente abriu. Os campos completos estão na documentação, e o panorama dos recursos da camada não oficial está em API do WhatsApp não oficial: vantagens.