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

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.

Visão geral do caso de uso

Envie um modelo de autenticação do WhatsApp com um código de registro único no corpo e um botão de copiar código. O usuário copia o código e completa o registro no seu aplicativo.

Exemplo de modelo

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

Desculpe, preciso do texto que você gostaria que fosse traduzido. Por favor, forneça o conteúdo.
  • {{1}}
    código de verificação de registro único (dígitos)
  • “Desculpe, preciso do texto que você gostaria que fosse traduzido. Por favor, forneça o conteúdo.”
    botão — fixo no modelo Meta
WhatsApp Business API for registration otp

Quando usá-lo

Procure isso quando o registro atingir a etapa de verificação de telefone e você precisar de um código de uso único entregue na inicialização fria antes que qualquer conversa no WhatsApp exista. Ele se encaixa no cadastramento de novas contas, fluxos de integração que substituem o OTP por SMS e integradores conectando a verificação de telefone nas APIs de registro de backend.

Whatsapp em vez de SMS OTP
Seu backend gera um código de registro único e o envia através de um template de autenticação aprovado pelo API 1MSG, para que a verificação ocorra pelo WhatsApp, em vez de um canal de SMS separado no cadastro.
Entrega para situações de início a frio
Apenas um modelo de autenticação aprovado pode abrir o chat no primeiro contato, que é a regra do canal para alcançar um usuário que nunca enviou uma mensagem para o seu negócio antes.
Entrada de código mais rápida
Uma variável de corpo transporta o código digital e um botão de cópia expõe o mesmo valor, para que o usuário cole no seu formulário de inscrição.
Menos falhas silenciosas de envio
Os modelos de autenticação exigem o OTP nos parâmetros do corpo e do botão copy-code; cargas úteis que contêm apenas o corpo retornam `sent: false`, e esse cenário conecta ambos a partir do mesmo valor de backend.

Fluxo de Trabalho

  1. Capturar evento

    O usuário inicia o registro e solicita a verificação por telefone.

    phone: "+…"

  2. Gera um código de uso único

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

    phone: "+…"

  3. Construir e enviar

    A mensagem do modelo é construída com o código no corpo e o parâmetro do botão copiar-código.

    POST /sendTemplate

  4. Entregue

    O usuário recebe WhatsApp e envia o código no seu formulário de inscrição.

    delivered

  5. Status rastreado

    O backend valida o código e conclui o registro.

    status: "read"

WhatsApp Business API for registration otp

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 do 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": true significam que 1MSG aceitou a mensagem para envio — não que ela já chegou ao telefone do cliente. Salve o campo id (parece com 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 retornos de entrega e hookInfo são vinculados a isso.

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

200 Claro!Webhook de status de entrega — carga recebida
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    enviado, entregue, lido — 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 chamadas de retorno, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída em poucos segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo aguardando 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.

Perguntas Frequentes

Sim — mensagens de WhatsApp de início a frio exigem um template aprovado pela 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 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”.
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