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.
Visão geral do caso de uso
Envia um código de confirmação de login único através de um modelo de autenticação do WhatsApp quando o seu backend detecta um acesso de um novo dispositivo, navegador ou local. O botão de copiar código ajuda o usuário a colar o código na sua tela de verificação.
Exemplo de modelo
{{1}} é seu código de verificação. Para sua segurança, não compartilhe este código com ninguém.
- {{1}}código de confirmação de login único (dígitos)
- “Copiar código”botão — fixo no modelo Meta

Quando usá-lo
Atinga para este cenário quando um usuário faz login de um novo dispositivo, navegador ou local e você deve confirmar que realmente é ele antes de conceder acesso, mas ainda não há sessão do WhatsApp aberta. Isso se encaixa nos fluxos de login de novo dispositivo e nova localização, alertas de segurança entregues pelo WhatsApp em vez de canais apenas SMS, e desenvolvedores, pequenas equipes ou agências conectando IAM ou backends de portal através da API 1MSG.
Como funciona
- Disparo
O usuário faz login a partir de um novo dispositivo, navegador ou local em seu aplicativo ou portal.
event·triggered - Detecta o novo login
Seu backend detecta o novo contexto de login e gera um código de confirmação temporário.
event·triggered - Criar & enviar
Uma mensagem modelo é construída com o código no corpo e o mesmo valor no parâmetro copy-code botão.
POST/sendTemplate - Entregue
O usuário recebe a mensagem do WhatsApp e copia ou lê o código.
delivered - Status rastreado
Seu backend valida o código enviado e conclui o login; erros de entrega são tratados de acordo com as regras da plataforma.
status:"read"

Implementação técnica
Pré-requisitos
- 1MSG API Key · Como obter a chave da API
- Conta do WhatsApp Business · Como Conectar WABA
- Modelo WhatsApp · Como Aprovar o Modelo WABA
- 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 1MSG aceitou a mensagem para envio — não que ela já tenha chegado ao telefone do cliente. Salve o id campo (parece wamid.…) para correlacionar os callbacks de entrega.
{
"sent": true,
"id": "wamid.HBgLMzgwNjM5...",
"message": "Message accepted for delivery"
}sentAceito para envio — não ainda no telefone do cliente
idArmazene isso; os callbacks de entrega e
hookInfoestão vinculados a isso
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.
{
"hooks": [
{
"id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
"type": "message",
"status": "sent",
"timestamp": "1654864094",
"recipient_id": "556123122026"
}
]
}statussent,delivered,read— ou um status de falha quando aplicávelidCorrelaciona o callback com o
idretornado pela chamada de enviotimestampSegundos Unix, como uma string
Se você preferir não receber callbacks, faça uma consulta em GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída em questão de segundos — mas o contrato da API não garante isso, portanto, nunca bloqueie um fluxo esperando por isso.
Erros comuns
| Status | Resposta | Causa |
|---|---|---|
| 200 | Message was not sent: template is not defined | namespace, template or language missing from the request body. |
| 200 | template name (…) does not exist in <language> | The template is approved in a different language than the one requested. |
| 200 | Message was not sent: provide chatId, phone, bsuid, or username | No recipient the channel could resolve. |
| 403 | access denied | The token is wrong, or belongs to a different channel than the URL. |
| 429 | too many requests. please try later | The channel is over its send rate. |

