💰 Respostas service deixam de ser grátis em 1º outMais
1msg official logo

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.

Visão geral do caso de uso

Envia um código de confirmação de acesso único através de um modelo de autenticação do WhatsApp quando o usuário precisa verificar a identidade antes de utilizar um serviço protegido. O botão de copiar código agiliza a entrada no seu formulário de acesso ou verificação.

Modelo de exemplo

{{1}} é o 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 confirmação de acesso a serviço único (dígitos)
  • “Copiar código”
    botão — fixo no modelo da Meta
WhatsApp Business API for service access confirmation

Quando usar isso

Acesse este cenário quando um usuário solicitar acesso a um serviço, recurso ou área do portal protegido e você precisar de um código único em um início a frio antes que qualquer sessão do WhatsApp exista. Isso se aplica à verificação de entrada no serviço, verificações adicionais antes de desbloquear recursos premium ou restritos, e equipes enviando portais seguros para desenvolvedores, pequenas equipes e agências.

Acesso a serviço de inicialização a frio em conformidade
Um modelo de autenticação aprovado inicia a conversa sem uma sessão existente, para que o código de confirmação de acesso possa chegar ao usuário no primeiro contato, em vez de ficar aguardando dentro da janela de resposta de 24 horas.
Entrada de código mais rápida no seu formulário de acesso
O botão de copiar-código contém os mesmos dígitos que a variável única do corpo, assim o usuário cola o OTP no seu formulário de acesso ou verificação em vez de digitá-lo novamente a partir do chat.
Verificação onde o número de telefone já reside
Quando a conta telefônica estiver registrada em formato internacional, o backend enviará o código de uso único através do WhatsApp para que a confirmação chegue a um canal que os usuários já conferem, em vez de uma caixa de entrada de SMS filtrada.
Enviar 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 apenas do corpo que retorna `sent: false`.

Como funciona

  1. Atos do cliente

    O usuário solicita acesso a um serviço ou recurso protegido e insere seu telefone.

    user action

  2. Construir & enviar

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

    POST /sendTemplate

  3. Copia o código

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

    user action

  4. Entregue

    O backend valida e completa o acesso ao serviço.

    delivered

WhatsApp Business API for service access confirmation

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como obter a Chave de API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo do 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 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; as callbacks 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 POSTs atualizações de status para seu endpoint HTTPS em um dado hooks[].

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 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 geralmente é concluída em 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.

FAQ

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

Relacionado

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

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