Pular para o conteúdo

Templates

Templates de autenticação

Códigos de verificação (OTP) pelo WhatsApp: os 3 tipos de botão, o handshake no app Android e o envio com type otp, sem o código ficar gravado.

Um template de autenticação leva um código de uso único (login, confirmação de cadastro, troca de senha). A Meta fixa o texto; você escolhe o botão, a validade e o idioma. O código é seu: o Messajo não gera nem confere códigos, só entrega, e não grava o código em lugar nenhum.

otp_type O que o contato vê Requisito
COPY_CODE botão Copiar código nenhum
ONE_TAP botão que preenche o código no seu app Android handshake no app; supported_apps
ZERO_TAP o código entra no app sozinho, sem toque handshake no app; supported_apps; aceitar os termos da Meta (zero_tap_terms_accepted: true)

Quando o app não fez o handshake (ou o contato está no iPhone), ONE_TAP e ZERO_TAP viram Copiar código.

Janela do terminal
curl https://api.messajo.com/v1/templates/authentication \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connection_id": "conn_...",
"name": "codigo_login",
"languages": ["pt_BR", "en_US", "es"],
"add_security_recommendation": true,
"code_expiration_minutes": 10,
"message_send_ttl_seconds": 300,
"button": {
"otp_type": "ONE_TAP",
"text": "Copiar código",
"autofill_text": "Preencher",
"supported_apps": [{ "package_name": "com.suaempresa.app", "signature_hash": "K8a/AINcGX7" }]
}
}'
  • Volta um template por idioma (até 20), em revisão na Meta, como os outros templates.
  • add_security_recommendation acrescenta “Para sua segurança, não compartilhe este código”.
  • code_expiration_minutes (1 a 90) acrescenta o rodapé com a validade.
  • message_send_ttl_seconds (30 a 900): depois desse tempo sem entregar, a Meta desiste (o código já teria vencido).
  • supported_apps: de 1 a 5 apps, cada um com o package_name e o signature_hash de 11 caracteres.

POST /v1/templates/authentication/preview com os mesmos campos mostra o texto que a Meta vai gerar, sem criar nada. No painel, Templates → Novo template → Autenticação.

ONE_TAP e ZERO_TAP só funcionam se o seu app avisar o WhatsApp antes de você mandar o código:

  1. Gere o signature_hash do certificado que assina o app (o mesmo hash de 11 caracteres da SMS Retriever API do Google).
  2. No app, logo antes de pedir o código ao seu backend, mande o intent de handshake para o WhatsApp (com.whatsapp e com.whatsapp.w4b) com um PendingIntent do seu app.
  3. Para ONE_TAP, receba o código na Activity que trata com.whatsapp.otp.OTP_RETRIEVED; para ZERO_TAP, num BroadcastReceiver com o mesmo action.

O passo a passo com código Kotlin está na documentação da Meta. Sem handshake válido, o botão cai para Copiar código.

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b0c…" \
-d '{
"connection_id": "conn_...",
"to": "5511999990001",
"type": "otp",
"otp": { "template": { "name": "codigo_login", "language": "pt_BR" }, "code": "482913" }
}'
  • Use template_id (tpl_…) ou template (nome e idioma), um dos dois.
  • code: de 4 a 15 letras ou números.
  • O template precisa ser AUTHENTICATION e estar aprovado; senão 422 otp_template_invalid.
  • Não há janela de 24 h: template sai a qualquer hora.

O código só existe na chamada à Meta. A mensagem guardada, os eventos (message.sent, message.status), os logs e a resposta guardada para a Idempotency-Key levam code: "••••" e otp: true. Você confere o código digitado contra o que o seu sistema gerou, nunca contra o Messajo.

Boas práticas: código curto e com validade curta, limite de tentativas no seu backend e um código novo a cada pedido.