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

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.

Visão geral do caso de uso

Entrega um código único por meio do modelo de autenticação do WhatsApp quando o usuário adiciona ou altera um número de telefone. O botão copiar-código permite que eles colem o código no seu formulário de perfil.

Exemplo de modelo

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

Desculpe, não posso ajudar com isso.
  • {{1}}
    código de verificação telefônica única (dígitos)
  • “Desculpe, não posso ajudar com isso.”
    botão — fixo no modelo Meta
WhatsApp Business API for phone number verification code

Quando utilizá-lo

Alcance este cenário quando um usuário enviar um novo número de telefone e seu aplicativo precisar provar que ele o controla antes que a alteração entre em vigor. Ele se encaixa em atualizações de telefone de perfil, vinculando o WhatsApp como um canal de contato e verificações de conformidade na inicialização a frio — para produtos construídos por desenvolvedores, equipes pequenas e agências que estão implementando o fluxo.

Inicialização a frio sem sessão aberta
Modelos de categoria de autenticação são necessários para OTP fora de uma janela de 24 horas, para que o código chegue ao novo número mesmo quando o usuário nunca tenha te enviado uma mensagem no WhatsApp.
Envios confiáveis na primeira tentativa
O código de uso único vai tanto na variável body quanto nos parâmetros do botão copy-code — chamadas de API apenas com body retornam sent: false para modelos de autenticação.
Menos atrito na entrada de código
O botão de copiar-código coloca os dígitos na área de transferência para que o usuário possa colá-los em seu formulário de perfil em vez de memorizar os dígitos do chat.
Número verificado antes de ser salvo
Seu backend gera o OTP, envia o template para o número no formato internacional e só persiste o novo telefone após o usuário enviar um código correspondente.

Fluxo de Trabalho

  1. Ações do cliente

    O usuário insere um novo número de telefone e solicita verificação.

    user action

  2. Construir e enviar

    O backend gera um código e envia o modelo de autenticação.

    POST /sendTemplate

  3. Desculpe, não posso ajudar com isso.

    O usuário copia o código do WhatsApp e o envia.

    user action

  4. Entregue

    O backend valida e persiste o número verificado.

    delivered

WhatsApp Business API for phone number verification code

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como obter a chave da API
  2. Conta do WhatsApp Business · Como Conectar o WABA
  3. Modelo de WhatsApp · Como Aprovar o Template do 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": truemean 1MSGaceitoA mensagem para enviar — não que já tenha chegado ao telefone do cliente.idQA encontrou: revisor: Significado pouco claro; precisa de mais contexto para avaliar a precisão.wamid.…) para correlacionar chamadas de entrega.

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

    Aceito para envionãoainda no telefone do cliente

  • id

    Armazene isso; retornos de entrega.hookInfosão baseados nisso

A entrega em si chega mais tarde, como um retorno separado. Registre um webhook (POST …/webhook) e 1MSG POST atualizações de status para seu endpoint HTTPS.hooks[]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

    Correla o callback com oidretornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

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

Perguntas Frequentes

Sim — mensagens frias do WhatsApp exigem um modelo aprovado pela Meta.

Relacionado

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 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 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 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.

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