1msg official logo

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.

Visão geral do caso de uso

Envie 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. O usuário copia o código e completa o cadastro no seu aplicativo móvel ou na web.

Modelo de exemplo

{{1}} é seu código de verificação. Para sua segurança, não compartilhe este código com ninguém.

Copiar código
  • {{1}}
    código de confirmação de registro de aplicativo único (dígitos)
  • “Copiar código”
    botão — fixo no modelo da Meta
WhatsApp Business API for app registration confirmation

Quando usar isso

Acesse este cenário quando um usuário inicia o registro em seu aplicativo móvel ou web e deve confirmar a inscrição com um código de uso único no WhatsApp antes que a conta seja ativada, mas nenhuma conversa existe ainda — uma mensagem em texto livre não é permitida no início frio. Isso se aplica ao onboarding de aplicativos móveis e web, equipes que substituem o OTP apenas por SMS durante o registro, e desenvolvedores, pequenas equipes ou agências integrando a confirmação de inscrição em fluxos de backend e IAM através da 1MSG API.

Confirme a inscrição sem um chat aberto
Um modelo de autenticação aprovado inicia a conversa em um início frio, então um código de confirmação de registro chega ao usuário logo após ele enviar os detalhes de cadastro, em vez de esperar dentro da janela de resposta de 24 horas.
Entrada de código mais rápida no app
Uma variável de corpo carrega o código digital e o botão de copiar código expõe o mesmo valor, então o usuário clica em Copiar código e cola na tela de registro em vez de digitar novamente de outro canal.
Menos envios de API rejeitados
Modelos de autenticação requerem o OTP tanto no corpo da mensagem quanto no botão de copiar código; fornecer ambos evita solicitações que retornam apenas no corpo e que resultam em `sent: false`.
Registro de auditoria claro para inscrição
O status de entrega é registrado quando o modelo é enviado, assim seu backend pode tentar novamente ou alertar sobre falhas enquanto valida o código que o usuário envia para ativar a conta.

Como funciona

  1. Atos do cliente

    O usuário envia o registro no aplicativo e solicita confirmação.

    user action

  2. Capturar evento

    O backend gera um código único e resolve o número de WhatsApp do usuário.

    phone: "+…"

  3. Construir e enviar

    O modelo de mensagem é construído com o código no corpo e o mesmo valor no parâmetro do botão de copiar-código.

    POST /sendTemplate

  4. Entregue

    O usuário recebe a mensagem do WhatsApp e copia ou lê o código.

    delivered

  5. Status rastreado

    O backend valida o código submetido e ativa a conta; os erros de entrega são tratados conforme as regras da plataforma.

    status: "read"

WhatsApp Business API for app registration confirmation

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como obter a Chave de API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. WhatsApp Modelo · 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_CODE="___"         # {{1}} otp code

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_CODE=$TEST_CODE"; 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 and button blocks.

# {{1}} otp code → ${TEST_CODE}
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_CODE}" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [ { "type": "text", "text": "${TEST_CODE}" } ]
    }

  ]
}
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 como 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 estão vinculados a isso

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 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 WhatsApp com início a frio 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 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 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