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

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.

Visão geral do caso de uso

O cenário envia ao usuário um template 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. O usuário pode tocar no botão para copiar o código e colá-lo em seu aplicativo ou portal.

Exemplo de modelo

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

Copy code
  • {{1}}
    código de verificação único (dígitos)
  • “Copy code”
    botão — fixo no modelo Meta
WhatsApp Business API for otp verification

Quando usar isso

Aplique este cenário quando um usuário fizer login, registrar-se ou confirmar uma ação sensível e você precisar de um código único no WhatsApp antes que qualquer conversa exista — uma mensagem de texto livre não é permitida no início frio. Ele se encaixa em fluxos de login e registro, checagens de segurança como redefinição de senha ou confirmação de pagamento, e agências ou integradores conectando um aplicativo web, aplicativo móvel ou backend de IAM por meio da API 1MSG.

Alcance usuários sem um chat aberto
Apenas um modelo de autenticação aprovado pode abrir a conversa; seu backend gera um código de curta duração e o envia via a API quando o login, registro ou verificação de etapa adicional é acionado.
Entrada de código mais rápida para usuários
Os dígitos chegam como uma única variável no corpo da mensagem 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 em seu app ou portal em vez de reescrever de outro canal.
Menos envios de API rejeitados
Os modelos de autenticação requerem o OTP tanto no corpo quanto no botão de copiar código; este cenário envia ambos, assim, solicitações que retornam `sent: false` e que têm apenas o corpo são evitadas.
Rastro de auditoria para tentativas.
O status de entrega é registrado quando o template é enviado, para que seu backend possa tentar novamente ou alertar sobre falhas de acordo com as regras da plataforma enquanto valida o código que o usuário envia.

Fluxo de Trabalho

  1. Gatilho

    O usuário começa o login, registro ou verificação adicional em seu aplicativo ou portal.

    event · triggered

  2. Capturar evento

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

    phone: "+…"

  3. Construa e envie

    Uma mensagem de modelo é construída com o código no corpo e o mesmo valor no parâmetro do botão de cópia de 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 fluxo; os erros de entrega são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for otp verification

Implementação técnica

Pré-requisitos

  1. 1MSG Chave da API · Como obter a chave da API
  2. Conta do WhatsApp Business · Como Conectar a WABA
  3. Modelo de WhatsApp · Como Aprovar o Modelo WABA
  4. Consentimento 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": true1MSG médioaceitoa mensagem para envio — não que já tenha chegado ao telefone do cliente.idcampowamid.…para correlacionar os retornos de entrega.

200 OKResposta
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Aceito para envio.nãoainda no telefone do cliente

  • id

    Armazene; chamadas de entrega ehookInfosão focados nisso

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

200 OKWebhook de status de entrega — payload recebido
{
  "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 a chamada de retorno com oidretornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você prefere não receber chamadas de retorno, participe.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 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.

Perguntas Frequentes

Sim — mensagens de WhatsApp em início frio exigem um modelo aprovado pelo Meta.

Relacionado

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 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.
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 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”.
Verificação OTP
WhatsApp Business API para código de verificação
Envia um template de autenticação do WhatsApp com um código de registro de uso único no corpo e um botão para copiar o código.
Verificação OTP
WhatsApp Business API para ação de conta OTP IA
Envia um código único via template de autenticação do WhatsApp quando o usuário confirma uma ação sensível da conta.

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