Skill de IA para API do WhatsAppMais
1msg official logo

WhatsApp Business API para notificação de status de verificação

O cenário envia ao cliente um modelo de WhatsApp personalizado quando o status de verificação ou eKYC deles muda.

Visão geral do caso de uso

O cenário envia para o cliente um modelo de WhatsApp personalizado quando o status de verificação ou eKYC muda. A mensagem inclui o nome do cliente, o processo de verificação e o novo rótulo de status. Um botão de URL estático abre a página de status de verificação ou o portal do cliente.

Exemplo de modelo

Olá, {{1}}! Seu {{2}} status foi atualizado para: {{3}}. Veja os detalhes usando o botão abaixo. Se você tiver dúvidas — estamos aqui para ajudar.

Ver status
  • {{1}}
    nome do cliente
  • {{2}}
    processo de verificação (por exemplo, verificação de identidade, verificação eKYC, revisão de documentos)
  • {{3}}
    novo rótulo de status (por exemplo, Aprovado, Rejeitado, Em análise, Ação necessária)
  • “Ver status”
    botão — fixo no modelo Meta
WhatsApp Business API for verification status notification

Quando usar isso

Acesse este cenário quando um cliente tiver enviado documentos de verificação ou concluído uma verificação de identidade e o status do caso mudar — aprovado, rejeitado, em revisão ou ação necessária — e você precisar notificá-lo proativamente antes que ele chame o suporte ou atualize um portal. Isso se aplica às equipes de fintech que processam filas de KYC, marketplaces que monitoram verificações de conformidade de vendedores e agências que conectam webhooks de eKYC ou status de conformidade ao WhatsApp.

Menos ligações perguntando "qual é o meu status de verificação?"
Três variáveis de corpo armazenam o nome do cliente, o rótulo do processo de verificação e o novo status, para que o cliente possa saber o resultado ou a fase de revisão sem precisar abrir o e-mail ou ligar para o suporte.
Detalhes do status a um toque de distância
Um botão de URL estático rotulado como Verificar status abre o portal de verificação ou a página de status — o link é fixo no modelo aprovado da Meta, enquanto apenas o texto do corpo é enviado via API.
Atualizações sem uma janela de chat aberta
Porque não há uma conversa ativa, o envio utiliza um modelo de WhatsApp aprovado via API 1MSG — o único canal que pode alcançar o cliente fora da janela de 24 horas da sessão.
Sem notificação de status manual para cada caso
Quando o provedor de eKYC ou o back office atualiza o status de verificação, a integração resolve o número de telefone e dispara o modelo nesse evento em vez de alguém copiar o texto do status manualmente.
Entrega registrada para acompanhamento de conformidade
O resultado da entrega é registrado após o envio, para que equipes de CRM ou de conformidade possam ver quem foi notificado e lidar com erros de acordo com as regras da plataforma.

Como funciona

  1. Atos do cliente

    O cliente envia documentos de verificação ou completa o fluxo de verificação de identidade.

    user action

  2. Status rastreado

    O back office, o provedor de eKYC ou a integração atualiza o status de verificação.

    status: "read"

  3. Resolve o telefone do destinatário

    O sistema resolve os campos de número de telefone do destinatário e status.

    status: "read"

  4. Construir & enviar

    Uma mensagem de modelo personalizado é construída com três variáveis de corpo e um botão de URL estático.

    POST /sendTemplate

  5. Entregue

    O cliente recebe a notificação do WhatsApp com o status de verificação atualizado.

    delivered

  6. Resultado da entrega está registrado

    O resultado da entrega é registrado; os erros são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for verification status notification

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. Modelo do WhatsApp · Como Aprovar Modelo WABA
  4. Opção do cliente · Como Gerenciar o Consentimento dos Clientes

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)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CUSTOMERNAME="___"         # {{1}} customer name
TEST_PROCESS="___"         # {{2}} process name
TEST_STATUS="___"         # {{3}} status label

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_PROCESS=$TEST_PROCESS" \
            "TEST_STATUS=$TEST_STATUS"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} process name → ${TEST_PROCESS}
# {{3}} status label → ${TEST_STATUS}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_PROCESS}" },
        { "type": "text", "text": "${TEST_STATUS}" }
      ]
    }

  ]
}
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."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    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 id campo (parece wamid.…) para correlacionar os callbacks de entrega.

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

    Aceito para envio — não ainda no telefone do cliente

  • id

    Armazene-o; os callbacks de entrega e hookInfo são chaveados nisso

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.

200 OKWebhook de status de entrega — dados que você recebe
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    sent, delivered, read — ou um status de falha quando aplicável

  • id

    Correla o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você prefere não receber callbacks, 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 aguardando por isso.

Erros comuns

StatusRespostaCausa
200Message was not sent: template is not definednamespace, template or language missing from the request body.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.
403access deniedThe token is wrong, or belongs to a different channel than the URL.
429too many requests. please try laterThe channel is over its send rate.

FAQ

Sim — mensagens de WhatsApp de inicialização a frio requerem um modelo aprovado pela Meta.

Relacionado

Serviço ao Cliente
WhatsApp Business API para notificação de reativação da conta
O cenário envia ao titular da conta um modelo personalizado do WhatsApp quando uma revisão ou verificação da conta é concluída e o acesso é restaurado.
Serviço ao Cliente
WhatsApp Business API para solicitação de confirmação de dados ou assinatura
O cenário envia ao cliente um modelo WhatsApp personalizado quando eles devem assinar um documento ou confirmar dados enviados para continuar.
Serviço ao Cliente
WhatsApp Business API para notificação de verificação rejeitada
O cenário envia ao cliente um modelo de WhatsApp personalizado quando sua eKYC ou verificação de identidade é rejeitada.
Serviço ao Cliente
WhatsApp Business API para confirmação de sucesso da verificação
O cenário envia ao cliente um modelo de WhatsApp personalizado quando a verificação de identidade ou eKYC é aprovada.
Serviço ao Cliente
WhatsApp Business API para solicitação de upload de documentos
O cenário envia um modelo de WhatsApp personalizado ao cliente quando um documento necessário está faltando e ele deve carregá-lo para continuar.
Serviço ao Cliente
WhatsApp Business API para notificação de transferência
O cenário envia para o cliente um modelo personalizado de WhatsApp quando um chamado de suporte é transferido para outro departamento.
Serviço ao Cliente
WhatsApp Business API para notificação de status de ticket
O cenário envia ao cliente um modelo de WhatsApp personalizado quando o status de um ticket de suporte muda.
Serviço ao Cliente
WhatsApp Business API para notificação de escalonamento
O cenário envia ao cliente um template de WhatsApp personalizado quando um ticket de suporte é escalado porque a resolução está levando mais tempo que o usual.

Crie para o WhatsApp em horas
sem complicações de infraestrutura