Skill de IA para API do WhatsAppMais
1msg official logo

WhatsApp Business API para solicitação de verificação

O cenário envia ao cliente um modelo de WhatsApp personalizado quando a verificação de identidade ou KYC é necessária, mas ainda não iniciada.

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 é necessária, mas ainda não foi iniciada. A mensagem inclui o nome do cliente, o processo de verificação e as instruções para os próximos passos. Um botão de URL estático abre o portal de verificação ou o fluxo de upload de documentos.

Modelo exemplo

Olá, {{1}}! Para continuar, por favor complete seu {{2}}. {{3}} Toque no botão abaixo para iniciar a verificação. Se você tiver perguntas — estamos aqui para ajudar.

Iniciar verificação
  • {{1}}
    nome do cliente
  • {{2}}
    processo de verificação (por exemplo, verificação de identidade, verificação KYC, revisão de documentos)
  • {{3}}
    instrução do próximo passo (por exemplo, faça o upload do documento de identidade e tire uma selfie no portal até sexta-feira)
  • “Iniciar verificação”
    botão — fixo no modelo Meta
WhatsApp Business API for verification request

Quando usá-lo

Acesse este cenário quando um cliente precisar concluir a verificação de identidade ou KYC antes de usar seu produto, receber pagamentos ou desbloquear recursos da conta — e ele ainda não tiver iniciado o fluxo, sem uma conversa aberta no WhatsApp para alcançá-lo em sessão. Isso se aplica a equipes de fintech que condicionam a ativação da conta ao KYC, marketplaces que exigem verificações de identidade do vendedor antes de entrar no ar, e agências que conectam gatilhos de conformidade ou onboarding do CRM de um cliente em lembretes de verificação no WhatsApp.

A verificação começa antes que limites ou bloqueios de pagamento afetem o cliente
Três variáveis de corpo carregam o nome do cliente, o rótulo do processo de verificação e a instrução do próximo passo, portanto, a solicitação explica por que a verificação é necessária em vez de um aviso genérico de conformidade.
Um toque no portal de verificação
Um botão de URL estático rotulado como Iniciar verificação abre o portal ou o fluxo de upload de documentos — o link é fixo no modelo aprovado da Meta enquanto apenas o texto do corpo é enviado via API.
Atingir clientes fora da janela de 24 horas
Como não há uma conversa ativa, o envio utiliza um modelo do WhatsApp aprovado através da API 1MSG — o único canal que pode solicitar verificação quando o cliente não escreveu primeiro.
Sem perseguição manual quando os portões de conformidade disparam
Quando um gatilho que requer verificação é acionado — registro, bloqueio de conformidade ou desbloqueio de recurso — o sistema resolve o número de telefone e envia o modelo nesse evento em vez de alguém copiar os detalhes manualmente.
Entrega registrada para acompanhamento de conformidade
O resultado da entrega é registrado após o envio, para que as equipes de CRM ou de conformidade possam ver quem foi solicitado a verificar e lidar com erros de acordo com as regras da plataforma.

Como funciona

  1. Atos do cliente

    Uma regra de negócios ou etapa de onboarding requer que o cliente complete a verificação de identidade ou KYC.

    user action

  2. Capturar evento

    O sistema detecta o evento que requer uma verificação e resolve o número de telefone do destinatário.

    phone: "+…"

  3. Construir & enviar

    A personalized template message is built with three body variables and a static URL button.

    POST /sendTemplate

  4. Entregue

    O cliente recebe a solicitação de verificação do WhatsApp com o contexto do processo e as instruções para o próximo passo.

    delivered

  5. Status rastreado

    O resultado da entrega está registrado; o cliente pode iniciar a verificação através do link do portal.

    status: "read"

WhatsApp Business API for verification request

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_NEXTSTEP="___"         # {{3}} next step

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_NEXTSTEP=$TEST_NEXTSTEP"; 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}} next step → ${TEST_NEXTSTEP}
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_NEXTSTEP}" }
      ]
    }

  ]
}
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 no 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 isso; os callbacks de entrega e hookInfo estão baseados 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 muitas vezes é concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo aguardando por ele.

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 frias do WhatsApp requerem um modelo aprovado pela Meta.

Relacionado

Verificação OTP
WhatsApp Business API para notificação de ekyc pendente
O cenário envia ao cliente um modelo de WhatsApp personalizado quando sua eKYC ou verificação de identidade está pendente de revisão.
Verificação OTP
WhatsApp Business API para notificação de ação kyc necessária
O cenário envia ao cliente um modelo de WhatsApp personalizado quando a revisão de KYC ou conformidade sinaliza uma ação necessária com prazo.
Verificação OTP
WhatsApp Business API para login seguro com otp
O cenário envia um modelo de autenticação do WhatsApp com um código de verificação único quando o usuário confirma o login em um serviço seguro.
Verificação OTP
WhatsApp Business API para confirmação de registro do aplicativo
Envia um modelo de autenticação do WhatsApp com um código de confirmação de registro de uso único no corpo da mensagem e um botão para copiar o código.
Verificação OTP
WhatsApp Business API para migração de SMS para WhatsApp OTP
Entrega um código de verificação único através de um modelo de autenticação WhatsApp quando seu produto troca a entrega de OTP de SMS para WhatsApp.
Verificação OTP
WhatsApp Business API para confirmação segura de ação otp
O cenário envia um modelo de autenticação do WhatsApp com um código de verificação quando o usuário deve confirmar uma ação segura.
Verificação OTP
WhatsApp Business API para confirmação de acesso ao serviço
Envia um código de confirmação único pelo modelo de autenticação do WhatsApp quando o usuário deve verificar a identidade antes de usar um serviço.
Verificação OTP
WhatsApp Business API para confirmação de autorização otp
Envia um código de autorização único através de um modelo de autenticação do WhatsApp quando o usuário deve confirmar o login ou acesso.

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