Skill de IA para API do WhatsAppMais
1msg official logo

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.

Visão geral do caso de uso

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 um prazo. A mensagem inclui o nome do cliente, a ação a ser completada e a data de vencimento. Um botão de URL estático abre o portal de verificação ou o fluxo de envio de documentos.

Modelo de exemplo

Olá, {{1}}! A verificação do seu KYC requer ação: {{2}}. Por favor, complete até {{3}} usando o botão abaixo. Se você tiver dúvidas — estamos aqui para ajudar.

Completar KYC
  • {{1}}
    nome do cliente
  • {{2}}
    ação KYC necessária (por exemplo, enviar comprovante de endereço, atualizar detalhes da empresa, completar verificação de identidade)
  • {{3}}
    prazo de ação (por exemplo, 15 de março de 2026)
  • “Completar KYC”
    botão — fixo no modelo da Meta
WhatsApp Business API for kyc action required notification

Quando usar

Alcance este cenário quando a revisão de KYC ou conformidade identificar que um cliente deve tomar uma ação específica — fazer upload de um documento, atualizar os detalhes da conta ou concluir uma verificação de identidade — antes de um prazo, e eles não têm um chat do WhatsApp aberto, então somente um modelo aprovado pode alcançá-los. Isso se encaixa em equipes de fintech ativando contas após o KYC, marketplaces mantendo a conformidade dos vendedores atualizada, e agências transmitindo eventos que requerem ação do CRM ou plataformas de onboarding para o WhatsApp.

Menos prazos de KYC perdidos
Três variáveis do corpo carregam o nome do cliente, a ação necessária e a data de vencimento para o WhatsApp, assim a notificação informa o que fazer e quando, em vez de um e-mail de conformidade genérico que é fácil de ignorar.
Um toque no portal de verificação
Um botão de URL estático rotulado como Completar KYC abre o portal ou o fluxo de upload fixo no modelo da Meta — apenas o texto do corpo é enviado via API enquanto o link permanece no modelo aprovado.
Alcance clientes sem um chat aberto
Como não há uma conversa ativa, o envio utiliza um modelo aprovado do WhatsApp via a API 1MSG — o único canal que pode notificar o cliente fora da janela de sessão de 24 horas.
Sem acompanhamento manual em grande escala
Quando o sistema de KYC ou conformidade sinaliza que uma ação é necessária, ele resolve o número de telefone e constrói o modelo a partir dos campos de revisão — ninguém digita as notificações de ação manualmente entre as contas.
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 rastrear quem recebeu o aviso de ação necessária antes que o acesso seja restrito.

Como funciona

  1. Atos do cliente

    A revisão de KYC ou conformidade sinaliza que o cliente deve concluir uma ação específica dentro de um prazo.

    user action

  2. Capturar evento

    O sistema resolve o número de telefone do destinatário e os campos que requerem ação.

    phone: "+…"

  3. Criar e enviar

    Uma mensagem de template personalizado é 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 notificação do WhatsApp com a ação requerida e a data de vencimento.

    delivered

  5. Status monitorado

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

    status: "read"

WhatsApp Business API for kyc action required notification

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 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_ACTION="___"         # {{2}} action name
TEST_DUEDATE="___"         # {{3}} due date

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_ACTION=$TEST_ACTION" \
            "TEST_DUEDATE=$TEST_DUEDATE"; 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}} action name → ${TEST_ACTION}
# {{3}} due date → ${TEST_DUEDATE}
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_ACTION}" },
        { "type": "text", "text": "${TEST_DUEDATE}" }
      ]
    }

  ]
}
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 isso; os retornos de chamada de entrega e hookInfo são baseados nisso

A entrega em si chega mais tarde, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG POSTa atualizações de status para seu endpoint HTTPS em um hooks[] dados de nível superior.

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 send

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber chamadas de retorno, faça uma consulta em 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 esperando 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 inicialização a frio 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 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.
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