💬 Shared Inbox do WhatsApp na nova PlataformaMais
1msg official logo

WhatsApp Business API para esclarecimento de dados de verificação

O cenário envia ao cliente um modelo WhatsApp personalizado se a verificação de identidade ou KYC não puder ser concluída até dados específicos serem aclarados.

Visão geral do caso de uso

O cenário envia ao cliente um modelo de WhatsApp personalizado quando a verificação de identidade ou KYC não pode ser concluída até que dados específicos sejam esclarecidos. A mensagem inclui o nome do cliente, o processo de verificação e o que precisa ser atualizado ou confirmado. Um botão de URL estático abre o portal de verificação ou o formulário de atualização de dados.

Modelo exemplo

Olá, {{1}}! Para completar seu {{2}}, precisamos esclarecer alguns detalhes: {{3}} Por favor, atualize as informações usando o botão abaixo. Se você tiver dúvidas — estamos aqui para ajudar.

Esclarecer detalhes
  • {{1}}
    nome do cliente
  • {{2}}
    processo de verificação (por exemplo, verificação de identidade, checagem KYC, revisão de documentos)
  • {{3}}
    detalhe do pedido de esclarecimento (por exemplo, confirme seu endereço registrado e data de nascimento)
  • “Esclarecer detalhes”
    botão — fixo no modelo Meta
WhatsApp Business API for verification data clarification

Quando usar isso

Aproxime-se deste cenário quando um cliente está no meio da verificação de identidade ou KYC e a equipe de revisão não consegue concluir a verificação até que dados específicos sejam esclarecidos ou corrigidos — e eles não têm um chat aberto no WhatsApp, portanto, apenas um modelo aprovado pode alcançá-los. Isso se aplica a equipes de fintech desbloqueando filas de KYC, marketplaces resolvendo dados de identidade ambígua de vendedores e agências enviando eventos de eKYC ou revisão de conformidade do CRM para o WhatsApp.

Verificações bloqueadas desbloqueadas com clareza em nível de campo
Três variáveis do corpo carregam o nome do cliente, o rótulo do processo de verificação e o detalhe da clarificação, para que o aviso nomeie exatamente o que deve ser corrigido em vez de um e-mail genérico de "verificação pendente".
Um toque no portal de atualização de dados
Um botão de URL estático rotulado como Esclarecer detalhes abre o portal de verificação ou o formulário de atualização fixo no modelo da Meta — apenas o texto do corpo é enviado pela API enquanto o link permanece no modelo aprovado.
Alcance clientes sem um chat aberto
Porque não há uma conversa ativa, o envio utiliza um modelo de WhatsApp aprovado via a API do 1MSG — o único canal que pode notificar o cliente fora da janela de sessão de 24 horas.
Sem perseguições manuais para cada caso de esclarecimento
Quando a verificação de revisão sinaliza a necessidade de esclarecimento de dados, a integração resolve o telefone e constrói o modelo a partir dos campos de revisão — ninguém reescreve os pedidos de esclarecimento manualmente em casos pendentes.
Entrega registrada para acompanhamento de conformidade
O resultado da entrega é registrado após o envio, para que as equipes de CRM ou conformidade possam acompanhar quem recebeu a solicitação de esclarecimento antes que a fila de verificação pare o processo ainda mais.

Como funciona

  1. Atos do cliente

    As bandeiras de revisão de verificação indicam que dados específicos do cliente devem ser esclarecidos para concluir a verificação.

    user action

  2. Capturar evento

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

    phone: "+…"

  3. Construir & enviar

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

    POST /sendTemplate

  4. Entregue

    O cliente recebe a solicitação de esclarecimento pelo WhatsApp com o contexto de verificação e detalhes necessários.

    delivered

  5. Status rastreado

    O resultado da entrega está registrado; o cliente pode atualizar os dados através do portal e continuar na sessão após a resposta.

    status: "read"

WhatsApp Business API for verification data clarification

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave da API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo WhatsApp · Como Aprovar o Modelo WABA
  4. Opt-in 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_REQUESTDETAIL="___"         # {{3}} request detail

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_REQUESTDETAIL=$TEST_REQUESTDETAIL"; 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}} request detail → ${TEST_REQUESTDETAIL}
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_REQUESTDETAIL}" }
      ]
    }

  ]
}
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 and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone. Save the id field (looks like wamid.…) to correlate delivery callbacks.

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 isso; as chamadas de entrega e hookInfo são baseadas 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

    Correlaciona o callback com o id retornado pela chamada send

  • 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 início a frio requerem um modelo aprovado pela Meta.

Relacionado

Serviço ao Cliente
WhatsApp Business API para confirmação de recebimento de documentos
O cenário envia ao cliente um modelo de WhatsApp personalizado quando os documentos necessários são recebidos e registrados no back office.
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 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.
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.

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