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

WhatsApp Business API para autenticação em dois fatores

O cenário envia um modelo de autenticação WhatsApp com um código de verificação único quando a autenticação em dois fatores é necessária após o login principal.

Visão geral do caso de uso

O cenário envia um modelo de autenticação do WhatsApp com um código de verificação único quando a autenticação de dois fatores é necessária após o login principal. O botão de copiar código permite que o usuário cole o código na sua tela de verificação sem precisar reescrever os dígitos do chat.

Modelo de exemplo

{{1}} é o 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 verificação de dois fatores único (dígitos)
  • “Copiar código”
    botão — fixado no modelo da Meta
WhatsApp Business API for two-factor authentication

Quando usá-lo

Acesse este cenário quando um usuário passar pelo login primário com uma senha ou SSO, mas precisar confirmar a identidade com um segundo fator no WhatsApp antes que a sessão seja aberta — geralmente não há um chat aberto ainda, então uma mensagem de texto livre não é permitida no início frio. Isso se encaixa na etapa de login após as credenciais, confirmações de alto risco como transferências ou acesso de administrador, e equipes integrando 2FA em aplicativos web, aplicativos móveis ou backends de IAM através da API 1MSG.

Segundo fator sem um chat aberto
Um modelo de autenticação aprovado abre a conversa no início frio, assim o código de verificação chega ao usuário logo após o login principal, em vez de esperar dentro da janela de resposta de 24 horas.
Inscrição de código mais rápida na etapa dois
Os dígitos aparecem como uma variável de corpo único e o mesmo valor no parâmetro do botão de copiar-código, assim o usuário toca em Copiar código e cola na tela de verificação em vez de digitá-los 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 requisições apenas no corpo que retornam `sent: false`.
Registro de auditoria para segurança de login
O status de entrega é registrado quando o modelo é enviado, para que seu backend possa tentar reenviar falhas e manter um registro claro enquanto valida o código antes de conceder acesso.

Como funciona

  1. Atos do cliente

    O usuário completa o login principal; seu backend decide que um segundo fator é necessário.

    user action

  2. Evento de captura

    Um código de verificação único é gerado e o número de WhatsApp do usuário é resolvido.

    phone: "+…"

  3. Construir & enviar

    Uma mensagem modelo é construída com o código no corpo e o mesmo valor no parâmetro do botão copia-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

    Seu backend valida o código enviado e completa o login; erros de entrega são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for two-factor authentication

Implementação técnica

Requisitos prévias

  1. 1MSG API Key · 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_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 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 associados 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

    Correlaciona o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber callbacks, faça polling em 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 de início frio requerem um modelo aprovado pela Meta.

Relacionado

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.
Verificação OTP
WhatsApp Business API para login de dispositivo novo otp
O cenário envia um modelo de autenticação WhatsApp com um código de verificação único quando o login é detectado de um novo dispositivo.
Verificação OTP
WhatsApp Business API para nova confirmação de login
Envia um código de confirmação de login único pelo modelo de autenticação do WhatsApp quando seu backend detecta login em novo dispositivo, navegador ou local.
Verificação OTP
WhatsApp Business API para verificação de código de telefone
Entrega um código único via template de autenticação do WhatsApp quando o usuário adiciona ou altera um número de telefone.
Verificação OTP
WhatsApp Business API para código OTP de senha
Envia um código de recuperação único através de um template de autenticação do WhatsApp quando o usuário inicia a redefinição de senha.
Verificação OTP
WhatsApp Business API para verificação de OTP
O cenário envia ao usuário um modelo de autenticação pelo WhatsApp com um código de verificação único no corpo da mensagem e um botão de copiar-código.
Verificação OTP
WhatsApp Business API para reenvio de OTP
Reenvia um novo código de verificação único via modelo de autenticação do WhatsApp quando o usuário toca em “Reenviar código”.

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