Envía códigos de verificación por WhatsApp

Usa códigos de verificación de WhatsApp para registro, inicio de sesión, recuperación de cuentas y verificación adicional de acciones confidenciales. Cuando un cliente elige WhatsApp, tu sistema envía una plantilla de autenticación. El cliente copia o autorrellena el código y tu backend lo valida.

¿Por qué usar WhatsApp para la verificación?

Añade otro canal de entrega junto con SMS

WhatsApp permite que los clientes reciban códigos por internet cuando la recepción de SMS no es confiable. Solo necesitan WhatsApp y una conexión a internet activa.

Reduce los pasos de ingreso del código

Los botones para copiar el código reducen la transcripción manual. Las experiencias de un toque (one-tap) y de cero toques (zero-tap) pueden reducir el cambio de aplicaciones en apps Android compatibles e integradas.

Optimiza el coste de una verificación completada

Compara los costes totales por canal por verificación correcta según el mercado, incluidas las tarifas de autenticación, las tarifas de autenticación internacional aplicables, los cargos de YCloud y el respaldo por SMS. Meta cobra por los mensajes entregados; un mensaje no entregado no genera la tarifa de mensaje de Meta correspondiente. Otros cargos dependen de tu plan de YCloud. Consulta precios de WhatsApp y precios de Meta.

Ubica el abandono en el flujo de verificación

Rastrea la aceptación de la API, la entrega de mensajes y la verificación correcta por separado para identificar los puntos de abandono. Tu backend debe rechazar códigos caducados, reutilizados o no válidos.

Antes de empezar

Inicia sesión en YCloud y conecta una WABA y un remitente.
Prepara la lógica de solicitud, generación, almacenamiento y validación de códigos. Esta guía utiliza la API de mensajes de WhatsApp; tu sistema gestiona el ciclo de vida del código. Para el servicio de verificación de YCloud, consulta Verify.
Prepara una clave de API del lado del servidor y un receptor de webhooks.
Usa un destinatario de prueba que haya solicitado el código. Una solicitud de código no constituye una autorización para marketing posterior.
Configura un canal de SMS e implementa las reglas de respaldo en tu backend.

1. Elige la experiencia del código

Experiencia e integración	Ejemplo
Copiar código Copia en WhatsApp y luego pega en tu sitio web o app. Funciona en todas las plataformas. Entrada de código y validación en el backend.
Un toque / Autorrelleno Toca Autofill para transferir el código a tu app de Android. Integra el SDK de OTP para Android de Meta y configura el nombre de tu paquete y el hash de la clave de firma de la app.
Cero toques Tu app de Android recibe el código sin cambiar a WhatsApp ni pulsar ningún botón. Integra el SDK de OTP para Android de Meta, configura el nombre de tu paquete y el hash de la clave de firma de la app, y acepta los términos de cero toques.	Pantalla ilustrativa de ingreso de código. Cero toques requiere Android.

Ofrece respaldo con copia de código si no se cumplen los requisitos para un toque o cero toques en Android. Para sugerencias de teclado en iOS, consulta las preguntas frecuentes a continuación.

2. Crea una plantilla de autenticación

Selecciona la WABA, el nombre y el idioma

Abre Templates para la WABA correspondiente en YCloud, selecciona Add Template y elige Authentication. Usa letras minúsculas, dígitos y guiones bajos para un nombre como login_verification. Elige el idioma de tu cliente y anota el nombre y el código de idioma aprobados exactos para el envío. Consulta Crear plantilla.

Configura el contenido y la acción del código

La autenticación utiliza texto de código predefinido, con avisos de seguridad y caducidad compatibles. No insertes textos promocionales comunes, URL, archivos multimedia ni emojis en el cuerpo. Elige Copy code, Autofill o Zero Tap. Para Autofill y Zero Tap, introduce el nombre real del paquete de Android y el hash de firma, y completa la integración de la app. Zero Tap también requiere aceptar las condiciones aplicables. Para la configuración de la API, usa el contrato supported_apps actual en lugar de los ejemplos anteriores de nivel superior con package_name y signature_hash. Sigue las guías de integración de autenticación para consultar los detalles del SDK para Android y del protocolo de enlace (handshake).

Configura tres ajustes de caducidad independientes

Ajuste	Qué controla	Ejemplo de cinco minutos
Caducidad del código en el backend	Momento en que tu servidor rechaza el código.	Cinco minutos después de la generación.
Aviso de caducidad visible	Lo que se le informa al cliente.	Cinco minutos, coincidiendo con tu política real.
Tiempo de vida (TTL) de entrega	Cuánto tiempo se puede intentar la entrega.	No debe superar el tiempo de vida útil restante del código, teniendo en cuenta el intervalo entre la generación y el envío.

Recomendamos configurar el TTL de entrega del OTP (messageSendTtlSeconds) en 30–60 segundos en tu plantilla de autenticación. Mantenlo dentro del tiempo de vida restante del código. YCloud admite 30–900 segundos, con un valor predeterminado de 10 minutos para las plantillas nuevas. El aviso de caducidad mostrado admite 1–90 minutos y no aplica la caducidad en el backend. El TTL de entrega detiene los intentos de entrega pendientes; no revoca los mensajes ya entregados. Consulta el contrato de la API de YCloud.

Enviar y comprobar disponibilidad

Envía la plantilla e inspecciona su estado de revisión real. Envía mensajes solo después de que esté aprobada y lista para usarse. Si es rechazada, revisa el motivo y sigue Revisión y ciclo de vida de plantillas. No dependas de un tiempo de aprobación fijo.

3. Enviar a través de la API

Envía inmediatamente después de que el cliente solicite un código. Elige el comportamiento de envío que necesite tu flujo:

Endpoint	Comportamiento
`POST /v2/whatsapp/messages/sendDirectly`	Envía de forma síncrona a la WhatsApp Business API; útil cuando el flujo de OTP necesita el resultado del envío de inmediato.
`POST /v2/whatsapp/messages`	Pone el mensaje en cola para su envío asíncrono.

Usa una plantilla de autenticación aprobada con cualquiera de los endpoints.

Preparar la solicitud

Autentícate en el servidor con X-API-Key.
Usa números en formato E.164, incluidos los códigos de país, para from y to.
Establece type en template y usa el nombre e idioma aprobados para la WABA seleccionada.
Proporciona el mismo código en el cuerpo y en los parámetros del botón de OTP.
Asocia tu solicitud de verificación con el ID de mensaje de YCloud. externalId facilita la conciliación, pero no garantiza la idempotencia.

Ejemplo de cuerpo de solicitud con botón para copiar código. Reemplaza los marcadores de posición; 123456 es ficticio y debe ser generado por tu sistema de verificación en producción:

{
  "from": "BUSINESS_PHONE_NUMBER",
  "to": "CUSTOMER_PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "APPROVED_TEMPLATE_NAME",
    "language": { "code": "APPROVED_LANGUAGE_CODE" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "text": "123456" }]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [{ "type": "text", "text": "123456" }]
      }
    ]
  },
  "externalId": "VERIFICATION_REQUEST_REFERENCE"
}

Los parámetros de envío para el botón de OTP usan sub_type: url; no uses una estructura ordinaria de botón de código de cupón de marketing. Consulta Autenticación con copia de código y Enviar un mensaje de WhatsApp. También puedes seleccionar Más → Copiar como cURL en una plantilla aprobada y contrastar los parámetros generados con su configuración. Una respuesta correcta de la API no confirma la entrega. Si una solicitud agota el tiempo de espera, inspecciona los registros de mensajes y los callbacks disponibles antes de volver a enviar.

4. Recibir actualizaciones de entrega

En Desarrolladores → Webhooks, crea un endpoint, introduce tu URL de callback y suscríbete a whatsapp.message.updated. Sigue la guía de Webhooks para la verificación de firmas, confirmaciones y reintentos. Asocia cada ID de mensaje con su solicitud de verificación:

Estado	Significado	Respuesta del flujo
`sent`	Enviado, sin confirmación de llegada al dispositivo del cliente.	Espera actualizaciones de entrega o fallo.
`delivered`	Entregado al destinatario.	Espera a que la validación del código se complete con éxito.
`read`	Se recibió una confirmación de lectura.	No marques la verificación como completada ni trates la ausencia de confirmaciones como un fallo.
`failed`	El envío o la entrega fallaron.	Revisa el error antes de corregir la configuración, reintentar o cambiar de canal.

Marca la verificación como completada solo cuando tu backend valide el código. Gestiona callbacks duplicados o tardíos sin permitir que un estado anterior sobrescriba uno posterior. Usa los Registros de mensajes para la investigación manual.

5. Diseñar la interfaz y el respaldo por SMS

Aclarar el canal de recepción

Antes del envío, indica que el código llegará por WhatsApp. Tras el envío, muestra el destino enmascarado, un mensaje de espera, una cuenta regresiva para reenviar y las alternativas disponibles. Permite que los clientes regresen y corrijan el número.

Estrategia y experiencia	Ejemplo de frontend
WhatsApp primero, respaldo por SMS Empieza con WhatsApp y ofrece SMS si la entrega falla o tarda demasiado.
El cliente elige Ofrece WhatsApp y SMS antes de enviar, luego muestra una cuenta regresiva para reenviar y la pantalla de introducción de código.

Configurar el respaldo por SMS

Configura el TTL de entrega del OTP en 30–60 segundos en tu plantilla de autenticación de WhatsApp y sincroniza tu temporizador de respaldo por SMS con él.

Activador	Regla de fallback a SMS
El envío de la API falla de forma explícita	Envía un SMS de inmediato e investiga el error de la API. Un timeout de solicitud por sí solo no es un rechazo explícito; revisa los registros de mensajes y las devoluciones de llamada.
Un webhook de `whatsapp.message.updated` reporta `failed`	Envía un SMS de inmediato e inspecciona el error. Un código habitual es `131026` (mensaje no entregable): puede que el número no esté registrado en WhatsApp, aunque son posibles otras causas.
El TTL de entrega ha expirado y tienes una confirmación de `sent`, pero ninguna de `delivered` o `read`	Envía un SMS si la solicitud de verificación sigue activa. Haz un seguimiento del plazo límite de entrega en tu backend; no reinicies el TTL cuando llegue un webhook tardío.
El mensaje de WhatsApp se entrega, la verificación se completa o el código ha expirado	No actives el fallback automático a SMS para esta solicitud.

Meta cobra por los mensajes de WhatsApp entregados. Un mensaje que expira sin entregarse no genera cargos por mensaje de Meta; los cargos de SMS se siguen aplicando. La ausencia de un webhook de entrega por sí sola no demuestra la falta de entrega, por lo que se pueden cobrar ambos canales si el mensaje de WhatsApp se entregó antes de expirar. Consulta las tarifas de WhatsApp. Envía SMS como máximo una vez por solicitud de verificación, incluso si las devoluciones de llamada se duplican o llegan tarde. Reutiliza el mismo código vigente o invalida el código anterior al generar uno nuevo. El fallback no debe ampliar el tiempo de vida del código.

6. Probar antes del lanzamiento

Prueba	Resultado esperado
Verificación normal	Los valores del cuerpo y del botón coinciden; un código vigente y correcto se valida con éxito.
Código incorrecto, expirado o reutilizado	El backend lo rechaza según la política y la interfaz explica el resultado.
Solicitud de nuevo código	La validez del código antiguo y del nuevo coincide con tu política.
Destinatario desconectado o retrasado	El TTL de entrega se mantiene independiente del tiempo de vida del código; la espera y el fallback siguen la configuración.
Condiciones de autocompletado de Android no compatibles	Un fallback funcional permite al cliente continuar.
iOS y múltiples dispositivos	Prueba las notificaciones, el copiado y el llenado en los clientes reales; no asumas un comportamiento idéntico.
Devoluciones de llamada duplicadas, tardías o timeout de solicitud	No generes resultados duplicados ni reenvíos descontrolados.
Fallback a SMS	Usa el destino correcto y un código válido; detén el proceso tras una verificación exitosa.

Tras el lanzamiento, compara la tasa de entrega, la latencia de entrega, la finalización de la verificación, la proporción de fallback a SMS y el coste por verificación exitosa por mercado, canal y dispositivo. Usa estos resultados para ajustar la prioridad de los canales y los umbrales de espera.

Escenario adicional: verificación iniciada por el cliente

En un flujo de verificación iniciada por el cliente, el cliente abre WhatsApp desde una app, envía un mensaje con la información para la verificación actual y luego regresa a la app. Este enfoque requiere un desafío de un solo uso, vinculación de sesión, expiración, protección contra repetición y confirmación del usuario.

Preguntas frecuentes

¿Cómo puedo comprobar si WhatsApp está instalado en Android o iOS?

En Android, declara com.whatsapp e com.whatsapp.w4b en las consultas de paquetes de tu manifiesto y, a continuación, usa el método del SDK de OTP para Android de Meta isWhatsAppInstalled(context) en una instancia de WhatsAppOtpHandler. En iOS, usa UIApplication.shared.canOpenURL(URL(string: "whatsapp://otp")!) y configura los permisos de consulta del esquema de URL que requiere tu app. Las comprobaciones de instalación ayudan a sugerir un canal en el dispositivo actual. No confirman que el número de teléfono introducido esté registrado en WhatsApp. Permite que los clientes confirmen su número de WhatsApp y elijan otro canal. Consulta las comprobaciones de instalación de Meta para Android e iOS.

¿iOS admite autocompletado con un toque (one-tap) o sin toques (zero-tap)?

iOS 26 y versiones posteriores habilitan las sugerencias de teclado de forma predeterminada para todas las plantillas de autenticación. iOS detecta el código en la notificación push de WhatsApp y ofrece una sugerencia de autocompletado con un solo toque en el teclado. No se requieren cambios en la integración. Las versiones anteriores de iOS no admiten esta experiencia de autocompletado; usa plantillas para copiar código. La integración del botón con un solo toque y sin toques en Android son experiencias diferentes; la opción sin toques es exclusiva de Android. Consulta las sugerencias de teclado de Meta.

¿Pueden los clientes leer códigos de verificación en dispositivos vinculados?

Los códigos de autenticación solo están disponibles en el dispositivo principal de WhatsApp del cliente. Los dispositivos vinculados muestran un mensaje enmascarado pidiéndole al cliente que revise su dispositivo principal. Esta función de seguridad de la Cloud API está habilitada de forma predeterminada, no requiere cambios en el código y no se puede configurar ni personalizar. Consulta la seguridad para dispositivos vinculados de Meta.

​¿Por qué usar WhatsApp para la verificación?

​Añade otro canal de entrega junto con SMS

​Reduce los pasos de ingreso del código

​Optimiza el coste de una verificación completada

​Ubica el abandono en el flujo de verificación

​Antes de empezar

​1. Elige la experiencia del código

​2. Crea una plantilla de autenticación

​Selecciona la WABA, el nombre y el idioma

​Configura el contenido y la acción del código

​Configura tres ajustes de caducidad independientes

​Enviar y comprobar disponibilidad

​3. Enviar a través de la API

​Preparar la solicitud

​4. Recibir actualizaciones de entrega

​5. Diseñar la interfaz y el respaldo por SMS

​Aclarar el canal de recepción

​Configurar el respaldo por SMS

​6. Probar antes del lanzamiento

​Escenario adicional: verificación iniciada por el cliente

​Preguntas frecuentes

​¿Cómo puedo comprobar si WhatsApp está instalado en Android o iOS?

​¿iOS admite autocompletado con un toque (one-tap) o sin toques (zero-tap)?

​¿Pueden los clientes leer códigos de verificación en dispositivos vinculados?