Ir al contenido

Plantillas

Plantillas de autenticación

Códigos de verificación (OTP) por WhatsApp: los 3 tipos de botón, el handshake en la app Android y el envío con type otp, sin que el código quede guardado.

Una plantilla de autenticación lleva un código de un solo uso (inicio de sesión, confirmación de registro, cambio de contraseña). Meta fija el texto; tú eliges el botón, la validez y el idioma. El código es tuyo: Messajo no genera ni verifica códigos, solo los entrega, y no guarda el código en ningún lugar.

otp_type Qué ve el contacto Requisito
COPY_CODE botón Copiar código ninguno
ONE_TAP botón que completa el código en tu app Android handshake en la app; supported_apps
ZERO_TAP el código entra en la app solo, sin tocar handshake en la app; supported_apps; aceptar los términos de Meta (zero_tap_terms_accepted: true)

Cuando la app no hizo el handshake (o el contacto usa iPhone), ONE_TAP y ZERO_TAP pasan a Copiar código.

Ventana de 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": "Completar",
"supported_apps": [{ "package_name": "com.tuempresa.app", "signature_hash": "K8a/AINcGX7" }]
}
}'
  • Devuelve una plantilla por idioma (hasta 20), en revisión en Meta, como las otras plantillas.
  • add_security_recommendation agrega “Por tu seguridad, no compartas este código”.
  • code_expiration_minutes (1 a 90) agrega el pie con la validez.
  • message_send_ttl_seconds (30 a 900): pasado ese tiempo sin entregar, Meta desiste (el código ya habría vencido).
  • supported_apps: de 1 a 5 apps, cada una con su package_name y el signature_hash de 11 caracteres.

POST /v1/templates/authentication/preview con los mismos campos muestra el texto que Meta va a generar, sin crear nada. En el panel, Plantillas → Nueva plantilla → Autenticación.

ONE_TAP y ZERO_TAP solo funcionan si tu app avisa a WhatsApp antes de que envíes el código:

  1. Genera el signature_hash del certificado que firma la app (el mismo hash de 11 caracteres de la SMS Retriever API de Google).
  2. En la app, justo antes de pedir el código a tu backend, envía el intent de handshake a WhatsApp (com.whatsapp y com.whatsapp.w4b) con un PendingIntent de tu app.
  3. Para ONE_TAP, recibe el código en la Activity que maneja com.whatsapp.otp.OTP_RETRIEVED; para ZERO_TAP, en un BroadcastReceiver con la misma action.

El paso a paso con código Kotlin está en la documentación de Meta. Sin un handshake válido, el botón pasa a Copiar código.

Ventana de 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": "es" }, "code": "482913" }
}'
  • Usa template_id (tpl_…) o template (nombre e idioma), uno de los dos.
  • code: de 4 a 15 letras o números.
  • La plantilla tiene que ser AUTHENTICATION y estar aprobada; si no, 422 otp_template_invalid.
  • No hay ventana de 24 h: la plantilla sale a cualquier hora.

El código solo existe en la llamada a Meta. El mensaje guardado, los eventos (message.sent, message.status), los logs y la respuesta guardada para la Idempotency-Key llevan code: "••••" y otp: true. Verificas el código escrito contra lo que generó tu sistema, nunca contra Messajo.

Buenas prácticas: código corto y de validez corta, límite de intentos en tu backend y un código nuevo en cada solicitud.