WhatsApp Business API para entrega — compartilhe localização

Visão geral do caso de uso

Este cenário envia uma localização no mapa com sendLocation durante a janela de atendimento ao cliente de 24 horas. As coordenadas, o nome do local e o endereço ajudam o comprador a navegar sem precisar copiar o texto.

Exemplo de modelo

Seu ponto de coleta está pronto. Toque no pin do mapa abaixo para navegar.

Quando usar

Alcance este cenário quando um pedido for movido para pronto para retirada e o comprador ainda precisar do ponto de coleta exato enquanto a sessão do WhatsApp estiver aberta. Isso se encaixa no e-commerce de clique e retire, onde digitar endereços manualmente causa desvios errôneos e contatos repetidos com o suporte.

Fluxo de Trabalho

1. Status rastreado

   Uma mudança no status do pedido indica que o pacote está pronto para retirada.

   status: "read"

2. Evento capturado

   Seu backend carrega coordenadas, nome do local e endereço da rua.

   phone: "+…"

3. Construa & envie

   sendLocation entrega o pin ao cliente na sessão ativa.

   POST /send_location

4. Entregue

   O cliente abre a navegação de mapas a partir do cartão de localização compartilhada.

   delivered

Implementação técnica

Pré-requisitos

1. Chave da API 1MSG · Como obter a Chave da API
2. Conta do WhatsApp Business · Como Conectar o WABA
3. Janela de sessão 24 horas · Como funciona a janela de 24 horas
4. Opt-in do cliente · Como Gerenciar o Consentimento
5. Webhook endpoint · Como Configurar Webhooks

Exemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===
API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendLocation"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "lat": "41.40338",
  "lng": "2.17403",
  "name": "Pickup point",
  "address": "Example street 1"
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
  *'"sent":true'*) ok=1 ;;
  *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
  echo "Message sent to client."
else
  echo "$BODY" >&2
  exit 1
fi

Status de resposta e entrega

HTTP 2xx e JSON "sent": true significam que 1MSG aceitou a mensagem para envio — não que ela já tenha chegado ao telefone do cliente. Salve o campo id (parece com wamid.…) para correlacionar os callbacks de entrega.

{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}

A entrega em si chega mais tarde, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG envia atualizações de status para seu endpoint HTTPS em uma carga útil de nível superior hooks[].

{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}

Se você preferir não receber chamadas de retorno, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando por isso.

Erros comuns

Perguntas Frequentes