WhatsApp Business API para contato de entregador.

Visão geral do caso de uso

Este cenário envia um cartão de contato do WhatsApp com sendContact durante a janela de atendimento ao cliente de 24 horas após um motorista ou mensageiro ser designado para o pedido.

Exemplo de modelo

Seu contato do mensageiro para esta entrega está no cartão abaixo.

Quando usar isso

Acesse este cenário quando a logística atribuir um motorista ou mensageiro a uma entrega ativa e o comprador precisar do número de telefone dessa pessoa sem copiar os dígitos de uma resposta em texto simples. Isso se adequa às equipes de entrega da última milha que compartilham contatos para salvar com um toque dentro de uma sessão de pedido aberto e operadores de frotas que passam o mensageiro designado, para que o cliente possa ligar diretamente do WhatsApp.

Fluxo de Trabalho

1. Gatilho

   A logística designa um motorista ou entregador para a entrega.

   event · triggered

2. Registrar evento

   Seu backend carrega o nome e telefone do entregador.

   phone: "+…"

3. Construa e envie.

   sendContact entrega o cartão de contato na sessão ativa.

   POST /send_contact

4. Entregue

   O cliente salva ou chama o entregador pelo WhatsApp.

   delivered

Implementação técnica

Pré-requisitos

1. 1MSG API Key · Como obter a chave da API
2. Conta do WhatsApp Business · Como Conectar WABA
3. Abre janela de sessão de 24 horas · Como funciona a janela de 24 horas
4. Escolha do cliente · Como Gerenciar o Consentimento dos Clientes
5. Endpoint de Webhook · 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}/sendContact"

# specialist display name (code_contract)
# specialist phone in E.164 format
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "contacts": [
    {
      "name": { "formatted_name": "Иван Курьер", "first_name": "Иван Курьер" },
      "phones": [{ "phone": "+998901234567", "type": "CELL" }]
    }
  ]
}
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 (parecido com wamid.…) para correlacionar os callbacks de entrega.

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

Delivery itself arrives later, as a separate callback. Register a webhook (POST …/webhook) and 1MSG POSTs status updates to your HTTPS endpoint in a top-level hooks[] payload.

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