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.
Os 3 tipos de botão
Seção intitulada “Os 3 tipos de botão”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.
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_recommendationacrescenta “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 opackage_namee osignature_hashde 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.
Handshake no app Android
Seção intitulada “Handshake no app Android”ONE_TAP e ZERO_TAP só funcionam se o seu app avisar o WhatsApp antes de você mandar o código:
- Gere o
signature_hashdo certificado que assina o app (o mesmo hash de 11 caracteres da SMS Retriever API do Google). - No app, logo antes de pedir o código ao seu backend, mande o intent de handshake para o WhatsApp (
com.whatsappecom.whatsapp.w4b) com umPendingIntentdo seu app. - Para
ONE_TAP, receba o código na Activity que tratacom.whatsapp.otp.OTP_RETRIEVED; paraZERO_TAP, numBroadcastReceivercom 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.
Mandar o código
Seção intitulada “Mandar o código”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_…) outemplate(nome e idioma), um dos dois. code: de 4 a 15 letras ou números.- O template precisa ser
AUTHENTICATIONe estar aprovado; senão422otp_template_invalid. - Não há janela de 24 h: template sai a qualquer hora.
O código não fica gravado
Seção intitulada “O código não fica gravado”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.