Cascada de canales

Declaras el orden de los canales en la petición. Si un canal no entrega a tiempo, el mismo código sigue por el siguiente.

Cómo funciona

La cascada es la lista channels de la petición, en orden de preferencia. Verify envía el código por el primer canal y, si no hay aprobación dentro de su tiempo de espera, pasa al siguiente.

{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }

• El código es uno solo. Cada paso lleva el mismo código, así que tu usuario puede escribir el primero que le llegue.
• Si omites channels (o envías []), se usan los canales encendidos de tu aplicación, en su orden: un teléfono toma WhatsApp y SMS, y un correo, el correo. Por defecto están todos encendidos, con sms → whatsapp para teléfonos.
• Solo canales encendidos. Una petición puede pedir otro orden o menos canales, pero no uno que tu aplicación tiene apagado: responde 403 con 10013.
• Hasta 4 pasos. Una cascada más larga responde 20006.
• El canal debe servir al destinatario: whatsapp y sms para teléfonos, email para correos. Otra combinación responde 20005.
• Un canal puede repetirse (["sms", "sms"]): el mismo código se envía otra vez por ese canal tras su tiempo de espera. Los nombres van en minúsculas; cualquier otra cosa responde 20005.

Los canales de tu aplicación

En la consola, en Aplicación → Política de verificación, eliges el orden de WhatsApp y SMS y qué canales quedan encendidos. Al menos uno tiene que quedar encendido, y los cambios rigen desde la siguiente verificación.

• Con el correo apagado, Verify rechaza las verificaciones a correos con 403 y 10013.
• Con WhatsApp y SMS apagados, rechaza las de teléfonos de la misma forma.
• Un rechazo así no crea la verificación y no se factura.

Canales disponibles

WhatsApp necesita dos cosas que configura el equipo de Inalambria: una plantilla de autenticación aprobada por Meta y un remitente de WhatsApp asignado a tu aplicación. Mientras falte alguna, el paso de WhatsApp se salta al instante y la cascada sigue por SMS: tu integración no cambia.

El correo también lo configura el equipo de Inalambria: el envío de correo activado en la plataforma, una plantilla de correo de tu cuenta en la plataforma de correo de Inalambria, con el campo que lleva el código, y una dirección remitente asignada a tu aplicación.

📘

Nota

Con una clave test_ los tres canales están disponibles sin configurar nada, y no se envía nada. Mira el entorno de pruebas.

🚧

Atención

Un correo tiene un solo canal posible, email, así que no hay respaldo. Si el correo no está configurado para tu aplicación, la verificación termina en failed al instante.

Cuándo pasa al siguiente canal

Que WhatsApp acepte un mensaje no confirma que llegó: WhatsApp no nos reporta la entrega. Por eso la cascada espera el tiempo del canal antes de probar por SMS, en lugar de saltar enseguida.

Cada paso espera el tiempo del canal antes de que empiece el siguiente, y un paso que empezaría después de expires_at nunca corre: deja expires_in más largo que (pasos − 1) × el tiempo del canal, o los últimos canales nunca se prueban.

Correo: cuando el envío es incierto

Que el proveedor de correo acepte un mensaje solo significa que lo puso en cola; tampoco nos reporta la entrega. A veces su respuesta ni siquiera dice eso: un tiempo de espera agotado, una conexión cortada, un error del servidor o una respuesta incompleta. En esos casos el correo pudo haber salido o no, así que Verify no lo vuelve a enviar:

• La verificación sigue pending con el mismo código. Tu usuario todavía puede escribirlo, hasta expires_at.
• Crear la verificación de nuevo la devuelve con 200 y no envía nada, aunque ya haya pasado resend_available_at. No consume límites y resend_available_at no se mueve.
• Ese envío no puede hacerla terminar en failed: salvo que tu usuario la apruebe o agote los intentos, termina en expired.

Qué canal ves en cada respuesta

• channel, en la creación: el primer paso de la cascada, aunque ese canal termine saltándose. En un 200 (reutilizada o reenviada), el paso en curso en ese momento.
• channel_used, en la aprobación: el paso que estaba en curso cuando tu usuario escribió el código.

Como todos los pasos llevan el mismo código, channel_used no garantiza que ese fuera el mensaje que tu usuario leyó.

El texto del mensaje

El SMS lo puedes escribir tú, en la consola, en Aplicación → Mensaje SMS. Lleva {{code}} una vez, donde va el código, y si quieres {{minutes}}, los minutos que dura; ningún otro marcador, hasta 300 caracteres. Mientras no escribas uno, sale el de la plataforma:

Tu codigo de verificacion es 418302. Vence en 5 minutos. No lo compartas con nadie.

Los minutos son el expires_in de la verificación, redondeado hacia arriba, no el tiempo que queda cuando sale ese mensaje en particular.

Sin tildes, en un SMS caben 160 caracteres. Una letra como «ó» o un emoji cambian la codificación y caben 70, así que un mensaje largo puede ocupar dos SMS. La consola muestra cuántos ocupa mientras lo escribes.

En WhatsApp se usa la plantilla de autenticación aprobada por Meta, igual para todas las cuentas. El campo brand aún no aparece en el texto de ningún canal.

El correo usa la plantilla de tu cuenta en la plataforma de correo de Inalambria. Verify solo completa el código: todo lo demás del mensaje sale de esa plantilla.

Cuándo falla

Una verificación termina en failed solo si cada paso falla de forma definitiva: el proveedor lo rechazó o no se pudo contactar, el canal no está disponible o configurado, o el operador confirmó que no se entregó. El correo es la excepción: un envío incierto nunca cuenta como fallo.

Si un canal aceptó el mensaje pero nadie confirmó la entrega, o el envío de correo fue incierto, no cuenta como fallo: la verificación sigue pending hasta vencer.