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

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.

Visão geral do caso de uso

Envia um código único e fresco via template de autenticação do WhatsApp quando o usuário confirma uma ação sensível da conta. O botão de copiar código ajuda a colar o código no seu diálogo de confirmação.

Exemplo de modelo

{{1}} é o 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 (dígitos)
  • “Copiar código”
    botão — fixo no modelo do Meta
WhatsApp Business API for account action otp

Quando usar isso

Acesse este cenário quando um usuário logado iniciar uma alteração sensível na conta — atualização de e-mail, configurações de pagamento, rotação de chave da API — e você precisar de um código único atualizado antes que a alteração seja confirmada. Ele é adequado para desenvolvedores que enviam portais, pequenas equipes com configurações de alto risco e agências que precisam de verificação adicional, além de um histórico de auditoria para revisões de segurança.

Aumento mais forte antes de mudanças sensíveis
O backend gera um código único quando o usuário inicia uma alteração protegida e o envia em uma variável de corpo através de um template de autenticação, vinculado à ação pendente até que a validação seja concluída.
Entrada de código mais rápida no celular
O botão de copiar-código carrega o mesmo OTP que o corpo da mensagem, então o usuário cola os dígitos na sua caixa de diálogo de confirmação em vez de digitá-los novamente no chat.
Verificação sem um chat aberto
Os modelos de categoria de autenticação entregam o OTP mesmo quando nenhuma sessão de suporte está aberta, assim o step-up funciona em cold start sem precisar de uma conversa ativa primeiro.
Entrega de OTP pronta para auditoria
Cada envio coloca o código no corpo e o botão de copiar código de acordo com as regras do template de autenticação, para que as análises de segurança possam registrar a entrega do OTP juntamente com mudanças de configurações de alto risco.

Fluxo de Trabalho

  1. Desencadear

    O usuário inicia uma mudança de conta protegida.

    event · triggered

  2. Crie e envie

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

    POST /sendTemplate

  3. Ações do cliente

    O usuário copia o código e confirma a ação.

    user action

  4. Entregue

    O backend valida e aplica a mudança.

    delivered

WhatsApp Business API for account action otp

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 do WhatsApp · Como Aprovar o Modelo do WABA
  4. Opção do cliente · Como Gerenciar o Consentimento

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 isso; as chamadas de entrega e hookInfo são baseadas nisso.

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

200 OKWebhook de status de entrega — payload recebido
{
  "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

    Correlaciona o callback com o id retornado pela chamada de envio.

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber callbacks, 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 aguardando.

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 cold-start requerem um modelo 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 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