1msg official logo

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.

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 de uso único quando o usuário deve confirmar uma ação segura antes que ela seja executada. O botão de copiar código permite que o usuário cole o código na sua tela de confirmação sem precisar reescrever os dígitos do chat.

Modelo de exemplo

{{1}} é 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 ação segura de uso único (dígitos)
  • “Copiar código”
    botão — fixado no modelo da Meta
WhatsApp Business API for secure action confirmation otp

Quando usá-lo

Alcance este cenário quando um usuário inicia uma ação segura ou sensível em seu sistema — aprovação de pagamento, confirmação de transferência, exportação de dados ou uma operação privilegiada — e você precisa de um código de uso único no WhatsApp antes que a ação seja executada. Geralmente, ainda não há um chat aberto, então uma mensagem de texto livre não é permitida no início. Isso se encaixa em fintechs e portais administrativos, portões de confirmação antes de mudanças de alto impacto, e equipes integrando a confirmação de ação segura em aplicativos web, aplicativos móveis ou backends através da 1MSG API.

Confirme a intenção antes que uma ação segura seja executada
O backend gera um código de curta duração quando o usuário inicia uma operação sensível e o envia em uma variável de corpo através de um modelo de autenticação, vinculado à ação pendente até que a validação seja concluída.
Entrada de código mais rápida no mobile
O botão de copiar código carrega o mesmo OTP que o corpo da mensagem, para que o usuário cole os dígitos no seu diálogo de confirmação em vez de digitá-los novamente a partir do chat.
Verificação sem um chat aberto
Os modelos da categoria de autenticação entregam o OTP mesmo quando nenhuma sessão de suporte está aberta, assim a confirmação de ação segura funciona em início frio sem precisar de uma conversa ativa primeiro.
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 solicitações que contenham apenas o corpo e retornam `sent: false`.

Como funciona

  1. Gatilho

    O usuário inicia uma ação segura ou sensível em seu aplicativo ou portal.

    event · triggered

  2. Evento de captura

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

    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 código-copiar.

    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 ou rejeita a ação segura; erros de entrega são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for secure action confirmation otp

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave da API
  2. Conta 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 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 isso; os callbacks de entrega e hookInfo são chaveados nisso

A entrega em si chega mais tarde, como um retorno separado. Registre um webhook (POST …/webhook) e o 1MSG POSTa atualizações de status para o seu endpoint HTTPS em um payload hooks[]dados.

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

    Correla o callback com o id retornado pela chamada send

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber retornos de chamada, consulte 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 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.

FAQ

Sim — mensagens do WhatsApp de início frio requerem um modelo aprovado pela Meta.

Relacionado

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

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