Plantillas de autenticación de WhatsApp: cómo enviar OTP por WhatsApp

En resumen: Las plantillas de autenticación son la categoría de WhatsApp Business Platform dedicada a los OTP y los códigos de verificación. WhatsApp fija el texto del mensaje; tú solo proporcionas el código y eliges un botón de OTP (copiar código, autocompletado con un toque o sin toque). Por lo general, se aprueban casi al instante, rara vez se pausan y solo se cobran cuando se entregan. Esta guía explica en qué se diferencian de otras plantillas, cuándo usarlas, cómo crear y enviar una (desde el panel y mediante la API), en qué se diferencian la caducidad del código y el TTL del mensaje, y cuáles son las prácticas recomendadas para prevenir la mayoría de los problemas en producción.

Introducción

Si tu app envía OTP por SMS, ya conoces los inconvenientes: costos cada vez más altos, mensajes retrasados o filtrados y usuarios que nunca ven el código. Las plantillas de autenticación de WhatsApp te ofrecen otra opción. Los códigos llegan a una app que las personas ya revisan constantemente y, en Android, puedes ofrecer el autocompletado con un toque para que el código se introduzca directamente en tu app.

Esta guía explica qué son las plantillas de autenticación, en qué se diferencian de las plantillas de Marketing y Utilidad, cuándo puedes usarlas (y cuándo no) y cómo crear y enviar una, tanto desde el panel de Chakra como mediante la API.

¿Qué son las plantillas de autenticación?

Las plantillas de autenticación son una de las tres categorías de plantillas de WhatsApp Business Platform, junto con Marketing y Utilidad. Tienen un solo propósito: entregar contraseñas de un solo uso y códigos de verificación para confirmar la identidad de un usuario.

Qué las hace diferentes:

• El contenido está estandarizado. No puedes escribir texto personalizado para el cuerpo del mensaje. WhatsApp lo genera en el idioma de la plantilla ("{{1}} es tu código de verificación") y tú solo proporcionas el código.
• Requieren un botón de OTP. Es obligatorio incluir la opción de copiar el código o el autocompletado con un toque, o bien la opción sin toque, que no muestra ningún botón visible. Estos tipos de botones solo existen en esta categoría.
• El texto de caducidad es opcional. Puedes agregar un pie de página como "Este código vence en 5 minutos".
• Por lo general, la aprobación es instantánea, ya que el contenido está predefinido y no es promocional. Meta también señala que las plantillas de autenticación con botones de OTP tienen un riesgo mucho menor de pausarse que las de otras categorías.

Estructura de una plantilla de autenticación

Lo que ve el usuario:

482913 es tu código de verificación. Por tu seguridad, no compartas este código.

Este código vence en 5 minutos.

[ Copiar código ]

Tipos de botones: copiar código vs. autocompletado con un toque vs. sin toque

El comportamiento alternativo es importante. Una plantilla de autocompletado con un toque o sin toque también requiere que proporciones la etiqueta del botón para copiar el código. Si Meta no puede validar el proceso de autocompletado (por ejemplo, si la app no está instalada), el mensaje muestra un botón para copiar el código. Por eso, no creas dos botones, uno para "autocompletado y otro para copiar el código": la plantilla tiene un solo botón de OTP e incluye la opción alternativa de copiar el código.

Una nota sobre iPhone. El autocompletado con un toque y la opción sin toque son funciones de Android. Por separado, la documentación de Meta indica que, a partir del 15 de junio de 2026, en iOS 26 y versiones posteriores, las sugerencias del teclado ofrecen el autocompletado nativo de OTP desde la notificación push, sin que tengas que hacer ninguna integración.

Acerca del hash de la firma. Para el autocompletado con un toque y la opción sin toque, debes proporcionar el nombre del paquete de tu app de Android y un hash de firma de 11 caracteres derivado del certificado de firma de tu app. Una discrepancia es la razón más común por la que el autocompletado pasa silenciosamente a la opción de copiar el código, así que prueba en un dispositivo real antes de publicar. El SDK de OTP para Android de Meta simplifica este proceso y vale la pena usarlo.

Cuándo usar plantillas de autenticación

Úsalas solo para códigos de verificación:

• Inicio de sesión y registro (verificación de un número de teléfono)
• Autenticación de dos factores
• Recuperación de cuentas y restablecimiento de contraseñas
• Confirmación de identidad antes de realizar cambios importantes en una cuenta
• Verificación de nuevo en un dispositivo nuevo o después de un período de inactividad

Cuándo no usarlas

Las plantillas de autenticación son exclusivamente para códigos. Usarlas para cualquier otra cosa hace que las plantillas se rechacen o se recategoricen:

• Las actualizaciones de pedidos y las notificaciones de entrega corresponden a la categoría Utilidad.
• Las promociones, ofertas y campañas para volver a interactuar corresponden a la categoría Marketing.
• Todo contenido que no sea un código de verificación no corresponde a esta categoría.

El error inverso es igual de común: no pongas un OTP en una plantilla de Utilidad para evitar el formato fijo. Meta detecta el contenido de OTP y lo recategorizará o rechazará. Si tu mensaje incluye un código, corresponde a una plantilla de Autenticación, y eso también determina cómo se factura.

Requisitos y límites

Para la empresa

• Una cuenta de WhatsApp Business activa en WhatsApp Business Platform, disponible a través de proveedores como Chakra.
• Copiar código y un toque no requieren aprobación especial. Para usar cero toques, debes aceptar las condiciones de cero toques de Meta al crear la plantilla.

Para la plantilla

• El texto del cuerpo es fijo. No se puede personalizar ni agregar variables adicionales al código.
• Exactamente un botón de OTP.
• Texto de la etiqueta del botón: máximo 25 caracteres.
• Hash de firma (un toque y cero toques): exactamente 11 caracteres.
• Expiración del código (opcional): de 1 a 90 minutos.
• Procura que los códigos tengan los habituales 4 a 8 dígitos, que es el rango para el que están diseñados los flujos de autocompletado.

Para el destinatario

• El número debe tener una cuenta de WhatsApp activa. De lo contrario, la entrega fallará (verás el error 131026), por lo que una alternativa por SMS es una medida de respaldo sensata para los flujos críticos.
• Según la documentación de Meta, los mensajes de autenticación se entregan únicamente al dispositivo principal de WhatsApp del usuario.
• El autocompletado con un toque también requiere que tu aplicación esté instalada en un dispositivo Android.

Cómo crear una plantilla de autenticación

Opción 1: Desde el panel de Chakra

La gestión de plantillas de Chakra te permite crear plantillas en todas las categorías, incluida Autenticación, y se encarga de enviarlas a Meta y sincronizar el estado de aprobación.

1. Abre la gestión de plantillas y crea una nueva.
2. Elige la categoría Autenticación .
3. Asigna un nombre a la plantilla (letras minúsculas, números y guiones bajos) y selecciona el idioma.
4. Elige el tipo de botón: copiar código o autocompletado con un toque.
5. Para un toque, ingresa el nombre del paquete de Android y el hash de firma.
6. Activa o desactiva la recomendación de seguridad («Por tu seguridad, no compartas este código»).
7. Configura la expiración del código (de 5 a 10 minutos es lo habitual para los flujos de inicio de sesión).
8. Envía la plantilla. La aprobación suele ser instantánea.

Opción 2: A través de la API

Crea una plantilla para copiar código:

json

POST https://graph.facebook.com/v{version}/{WABA_ID}/message_templates

{
"name": "login_otp_copy_code",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }
]
}
]
}

Crea una plantilla de autocompletado con un toque (la etiqueta para copiar código es la alternativa integrada):

json

{
"name": "login_otp_autofill",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ONE_TAP",
"text": "Copy Code",
"autofill_text": "Autofill",
"package_name": "com.yourcompany.app",
"signature_hash": "K8a/AINcGX7"
}
]
}
]
}

Referencia de campos

Varios idiomas. El mismo nombre de plantilla puede existir en varios idiomas. El endpoint upsert de Meta te permite crear una plantilla de autenticación en varios idiomas con una sola llamada, en lugar de repetir la solicitud para cada idioma.

Enviar el código

Con el SDK de Chakra

El SDK de TypeScript de Chakra tiene un parámetro OTP, así que no tienes que ensamblar los componentes manualmente:

javascript

await client.whatsapp.templateMessages.send({
pluginId: "YOUR_PLUGIN_ID",
toPhoneNumber: "919999999999",
whatsappPhoneNumberId: "YOUR_PHONE_NUMBER_ID",
templateName: "login_otp",
otpCode: "496093",
});

Los números de teléfono deben incluir el código de país, sin + ni caracteres de formato.

Con el endpoint de formato Meta

Si prefieres el payload sin procesar de Meta a través del endpoint passthrough de Chakra, ten en cuenta un detalle que suele causar confusión: el código debe aparecer dos veces, una en el cuerpo y otra en el componente del botón.

bash

curl --request POST \
'https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v19.0/{whatsappPhoneNumberId}/messages' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919999999999",
"type": "template",
"template": {
"name": "login_otp",
"language": { "code": "en_US" },
"components": [
{
"type": "body",
"parameters": [ { "type": "text", "text": "482913" } ]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [ { "type": "text", "text": "482913" } ]
}
]
}
}'

Omitir el parámetro del botón es una causa común de los errores al enviar OTP. Usa una versión actual de Graph API en la URL y consulta la referencia de API de Chakra para ver los detalles de autenticación y de la solicitud.

La caducidad del código y el TTL del mensaje son ajustes distintos

Es fácil confundir estos dos ajustes:

• code_expiration_minutes controla el texto que se muestra al usuario («Este código vence en X minutos»). Indica durante cuánto tiempo es válido el código.
• message_send_ttl_seconds controla durante cuánto tiempo Meta intenta entregar el mensaje. Para las plantillas de autenticación, el valor predeterminado es de 10 minutos, y puedes reducirlo. Si el mensaje no se entrega dentro de ese plazo, Meta lo descarta y no se cobran los mensajes no entregados.

Configura ambos valores de forma deliberada y haz que coincidan con el período de validez del lado del servidor. Si vence el TTL y no recibiste ningún webhook de entrega, considera que el mensaje se descartó; ese es el momento natural para activar el envío alternativo por SMS.

El flujo OTP de principio a fin

1. El usuario ingresa su número de teléfono en tu aplicación o sitio.
2. Tu backend genera un código y llama a la API de envío.
3. WhatsApp entrega la plantilla de autenticación.
4. El usuario toca la opción de autocompletar (Android) o copia y pega el código.
5. Tu backend verifica el código e inicia la sesión del usuario.
6. Tu webhook recibe el estado de entrega para que puedas activar un envío alternativo si el mensaje nunca llega.

Precios

• Los mensajes de autenticación se cobran por mensaje entregado, según la tarifa de autenticación del país del destinatario (Consulta las tarifas por país). Algunos mercados también tienen una tarifa internacional de autenticación aparte para empresas que cumplen los requisitos.
• Los mensajes no entregados, incluidos los que se descartan después del TTL, no se cobran.
• Las tarifas varían según el país y cambian con el tiempo, así que consulta la tarifa actual de Meta antes de hacer proyecciones.
• Chakra no aplica ningún recargo a los mensajes de plantilla: pagas la tarifa vigente de Meta por los mensajes entregados correctamente.

Buenas prácticas

• Empieza con la opción de copiar el código. Funciona para todos los usuarios. Agrega la opción de un solo toque solo si tienes una aplicación para Android y puedes mantener el hash de firma.
• Configura un vencimiento breve, normalmente de 5 a 10 minutos, y ajusta el TTL para que coincida.
• Agrega un envío alternativo por SMS para los destinatarios que no puedan recibir mensajes de WhatsApp (131026) y para los mensajes que no tengan confirmación de entrega dentro del TTL.
• Limita la frecuencia de las solicitudes OTP en tu servidor, con períodos de espera entre reenvíos, para evitar el uso indebido y el spam accidental. Ten en cuenta también los límites de frecuencia de la API durante los picos de tráfico (Chakra aplica un límite de 200 llamadas por minuto).
• Crea una versión para cada idioma que ofrezcas, con el mismo nombre de plantilla siempre que sea posible.
• Supervisa los webhooks de estado (enviado, entregado, leído, fallido) para detectar pronto los problemas de entrega.
• Nunca uses plantillas de autenticación para contenido que no sea OTP. Es la forma más rápida de que cambien su categoría.
• Prueba el autocompletado en un dispositivo Android real antes del lanzamiento. Los problemas con el hash de firma solo aparecen ahí.

Preguntas frecuentes

¿Puedo personalizar el texto del cuerpo de una plantilla de autenticación? No. El cuerpo está estandarizado. Las únicas partes de texto que puedes configurar son el aviso de seguridad, la línea de vencimiento y las etiquetas de los botones.

¿Es necesario aprobar las plantillas de autenticación? Pasan por el proceso de envío habitual, pero, como el contenido está predefinido, normalmente se aprueban casi de inmediato.

¿Qué pasa si envío un OTP en una plantilla de Utility? Meta detecta el contenido OTP y lo reclasifica como autenticación o lo rechaza. Usa la categoría correcta desde el principio.

¿El autocompletado con un solo toque funciona en iPhone? No. Las opciones de un solo toque y cero toques son funciones de Android. Los usuarios de iPhone reciben el flujo para copiar el código y, en iOS 26 y versiones posteriores, Meta indica que las sugerencias del teclado pueden completar el código de forma nativa desde la notificación.

¿Puedo enviar la misma plantilla en varios idiomas? Sí. Un nombre de plantilla puede tener una versión aprobada independiente para cada idioma, y eliges el código de idioma al enviar.

¿Cuántos dígitos puede tener el código? Usa entre 4 y 8 dígitos, el estándar en el que se basan los flujos de autocompletado.

Conclusión

Las plantillas de autenticación son una de las categorías más sencillas de configurar correctamente: contenido fijo, aprobación inmediata y un botón OTP que se adapta a tu plataforma. Si estás creando flujos de inicio de sesión, registro o autenticación de dos factores, vale la pena agregarlas junto con los SMS o usarlas como tu canal principal para OTP cuando tus usuarios ya se comunican por WhatsApp. Para consultar la referencia completa de plantillas y envíos, visita la documentación de plantillas de autenticación de Meta y la documentación de API de Chakra.