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

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.
Como funciona
- Construa & envie
O usuário ativa a verificação em um fluxo que anteriormente enviou SMS com OTP.
POST/sendTemplate - Gera um código
O backend gera um código e envia o modelo de autenticação via WhatsApp.
POST/sendTemplate - Ações do cliente
O usuário copia o código do WhatsApp e o envia no seu aplicativo.
user action - Entregue
O backend valida o código e completa a mesma etapa que o antigo caminho de SMS.
delivered

Implementação técnica
Pré-requisitos
- Chave da API 1MSG · Como obter a chave da API
- Conta do WhatsApp Business · Como Conectar WABA
- Modelo WhatsApp · Como Aprovar 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_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.
{
"sent": true,
"id": "wamid.HBgLMzgwNjM5...",
"message": "Message accepted for delivery"
}sentAceito para envio — não ainda no telefone do cliente
idArmazene isso; os retornos de chamada de entrega e
hookInfosã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.
{
"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 sendtimestampSegundos 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
| 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. |

