1msg official logo

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.

Visão geral do caso de uso

Entrega um código de verificação único através de um modelo de autenticação do WhatsApp quando seu produto troca a entrega de OTP de SMS para WhatsApp. O botão de copiar código mantém a entrada rápida em seu formulário de login ou cadastro existente.

Modelo de exemplo

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

Copiar código
  • {{1}}
    código de verificação único para migração de SMS para WhatsApp (dígitos)
  • “Copiar código”
    botão — fixado no modelo Meta
WhatsApp Business API for sms to whatsapp otp migration

Quando usá-lo

Acesse este cenário quando você estiver substituindo códigos de uso único de SMS pela entrega de OTP via WhatsApp e ainda precisar de conformidade de início a frio no primeiro envio. Isso se encaixa em projetos de migração de canal, equipes que desejam reduzir custos com SMS ou melhorar o alcance de entrega, e produtos que mantêm a mesma validação de backend enquanto mudam o transporte para WhatsApp para desenvolvedores, pequenas equipes e agências.

Migrar sem reescrever a validação
Uma variável no corpo carrega os dígitos OTP no modelo de autenticação, então seu backend mantém a mesma lógica de gerar e verificar, enquanto apenas o canal de entrega muda de SMS para WhatsApp.
Alcance os usuários onde eles já conversam
WhatsApp entrega o código em um aplicativo que os usuários abrem diariamente, o que reduz mensagens OTP perdidas em comparação com filtros de SMS e roteamento atrasado de operadoras.
Início a frio em conformidade no primeiro envio migrado
Um modelo de autenticação aprovado com parâmetros de corpo e botão de copiar-código abre a conversa sem uma sessão, assim o primeiro envio de código pós-migração permanece dentro da política do WhatsApp.
Send sucede na primeira tentativa
Modelos de autenticação requerem o OTP tanto no corpo da mensagem quanto nos dados do botão de copiar código; fornecer ambos evita um envio somente do corpo que retorna `sent: false`.

Como funciona

  1. Construa & envie

    O usuário ativa a verificação em um fluxo que anteriormente enviou SMS com OTP.

    POST /sendTemplate

  2. Gera um código

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

    POST /sendTemplate

  3. Ações do cliente

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

    user action

  4. Entregue

    O backend valida o código e completa a mesma etapa que o antigo caminho de SMS.

    delivered

WhatsApp Business API for sms to whatsapp otp migration

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 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_OTPCODE="___"         # {{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_OTPCODE=$TEST_OTPCODE"; 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_OTPCODE}
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_OTPCODE}" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [ { "type": "text", "text": "${TEST_OTPCODE}" } ]
    }

  ]
}
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 isso; os retornos de chamada de entrega e hookInfo são baseados nisso

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 send

  • timestamp

    Segundos Unix, como uma string

Se você preferir 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 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 a frio exigem um modelo aprovado pela Meta.

Relacionado

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

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