WhatsApp Business API — repasse ao especialista com contato

Visão geral do caso de uso

Esse cenário envia um cartão de contato do WhatsApp com sendContact durante a janela de atendimento ao cliente de 24 horas. O cliente recebe o nome e o telefone do especialista sem precisar copiar os dígitos manualmente.

Exemplo de modelo

Por favor, entre em contato com nosso especialista usando o cartão de contato abaixo.

Quando usá-lo

Acesse este cenário quando o suporte de primeira linha tiver aprovado a escalada para um especialista nomeado e a janela de atendimento ao cliente de 24 horas ainda estiver aberta. Ele se encaixa nos fluxos de trabalho do helpdesk, onde um especialista humano precisa assumir sem perder o contexto do chat — especialmente quando compartilhar um número de telefone como texto simples correria o risco de uma discagem errada.

Fluxo de Trabalho

1. Desencadear

   Um agente marca o ticket como pronto para escalonamento especializado.

   event · triggered

2. Capturar evento

   Seu backend carrega o nome de exibição do especialista e o número de telefone.

   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 especialista pelo WhatsApp.

   delivered

Implementação técnica

Pré-requisitos

1. Chave da API 1MSG · Como obter a Chave da API
2. Conta comercial do WhatsApp · Como Conectar o WABA
3. Janela de sessão aberta 24 horas · Como funciona a janela de 24 horas
4. Consentimento 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": "Jane Specialist", "first_name": "Jane Specialist" },
      "phones": [{ "phone": "+12025550199", "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 (que se 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 retorno separado. Registre um webhook (POST …/webhook) e 1MSG envia atualizações de status para o seu endpoint HTTPS em um payload hooks[] de nível superior.

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

Se você prefere 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 ela.

Erros comuns

Perguntas Frequentes