Saltar al contenido principal
Esta página forma parte de App de ejemplo: una integración completa de OneSignal, que sigue una app real de principio a fin. La app es Clean Beans, un turno de limpieza para hogares compartidos, creada con Expo (React Native) y un backend de Supabase. Clean Beans usa SMS para dos tareas que el push y el email no hacen bien: demostrar que un número de teléfono pertenece a la persona que lo ha escrito y llegar a alguien que todavía no tiene la app. Ambos se envían a un contacto sin procesar, un número de teléfono o una dirección de email, no a un External ID. Esa es la principal diferencia con todos los demás envíos de esta guía.

Verificar un número de teléfono con un código de un solo uso \

En User Profile, un usuario puede añadir un número de móvil. La app pide al backend que envíe por SMS un código de 6 dígitos, el usuario lo escribe y el backend lo comprueba. Solo entonces el número se considera verificado.
La tarjeta del número de teléfono en tres estados: introducción del número, introducción del código y verificado

Añadir un número de teléfono: introducir el número, introducir el código, verificado.

OneSignal entrega el mensaje de texto. No crea ni comprueba el código. Todo lo demás es tarea de tu backend.
1

Generar un código y guardarlo con hash

El código procede de una fuente aleatoria criptográfica. Solo se guarda un hash con clave, vinculado al usuario y al número de teléfono, de modo que la tabla por sí sola no permite recuperar los códigos. La clave es un secreto dedicado, OTP_HASH_SECRET, que no se usa para nada más. Ambas funciones se niegan a ejecutarse si no está definido.
supabase/functions/_shared/otp.ts
supabase/functions/send-otp/index.ts
2

Enviarlo por SMS a través de OneSignal

include_phone_numbers se dirige directamente al número. Si OneSignal no lo ha visto nunca, crea una suscripción SMS para él.
supabase/functions/send-otp/index.ts
3

Comprobar el código

El backend calcula el hash de lo que ha escrito el usuario y lo compara con el hash guardado. Cada intento fallido se cuenta. Tras cinco, el código deja de valer y hay que solicitar uno nuevo.
supabase/functions/verify-otp/index.ts
4

Registrar el número como suscripción SMS

Una vez que el backend confirma el código, la app añade el número al usuario que ha iniciado sesión.
src/lib/phone.ts
La app repite esto después de cada inicio de sesión, de modo que un número verificado acompaña al usuario a un dispositivo nuevo.
src/lib/phone.ts
Llama a addSms() después de login(), igual que con el email. Un envío a un número de teléfono sin procesar crea una suscripción que no pertenece a nadie. addSms() desde una app con sesión iniciada vincula esa suscripción al usuario. Hasta entonces, aparece en el panel como un registro de usuario independiente.

Proteger el endpoint \

Una función que envía un mensaje de texto bajo petición cuesta dinero cada vez que se ejecuta y es objetivo de abusos. Clean Beans aplica estos límites.
supabase/functions/send-otp/index.ts
El número verificado se guarda en su propia tabla. Solo el backend puede escribir en ella, así que la app no puede marcar un número como verificado y los demás miembros de un hogar no pueden leerlo.
supabase/migrations/028_phone_verification_and_invites.sql
Un número de teléfono por sí solo no es un permiso para enviarle mensajes. Para los códigos de verificación basta con un aviso junto al campo del teléfono, que debe indicar quién envía, qué enviará, que pueden aplicarse tarifas y cómo darse de baja.
src/components/PhoneVerificationCard.tsx

Invitar a alguien que todavía no es usuario \

En la pantalla Household, un miembro puede invitar a alguien por SMS o por email. La persona invitada no tiene cuenta, ni dispositivo registrado, ni External ID. El backend envía al contacto sin procesar, con un enlace que abre la pantalla de unión de la app.
El diálogo de invitación y el mensaje de texto de invitación que envía

Invitar a un compañero de casa por SMS o email, y el mensaje que recibe.

El mismo endpoint gestiona ambos canales. El SMS usa include_phone_numbers. El email usa email_to, con el asunto y el cuerpo HTML incluidos en la solicitud.
supabase/functions/send-invite/index.ts
El enlace es un Universal Link, configurado en Abrir la app desde enlaces web normales. Dos detalles hacen que siga funcionando:
  • El seguimiento de clics en el email está desactivado. El seguimiento reescribe los enlaces para que pasen por un dominio de seguimiento, y un enlace reescrito ya no abre la app.
  • El SMS no usa un enlace corto con seguimiento, por el mismo motivo.
Cuando la persona invitada instala la app e inicia sesión, las llamadas login() y addEmail() o addSms() de la app vinculan a su nuevo usuario la suscripción que creó la invitación.
La persona invitada no ha aceptado recibir mensajes de tu app. Las normas sobre SMS y emails no solicitados varían según el país y pueden ser estrictas. Clean Beans incluye este flujo para mostrar cómo funciona el envío a un contacto sin procesar, y limita a cada miembro a diez invitaciones al día. Antes de usar este patrón en producción, comprueba las normas de los lugares a los que envías y plantéate que sea la persona que invita quien envíe el mensaje desde su propio teléfono.

Lo que debes saber \

  • Se necesita un remitente. Elige un remitente predeterminado en Configuración > SMS o pasa sms_from en cada solicitud. Sin ninguno de los dos, la solicitud se rechaza con “A valid number is required for ‘From’ field”.
  • Una respuesta 200 no siempre significa que se haya enviado un mensaje. Comprueba que hay un id de mensaje en la respuesta, no solo el código de estado.
  • Guarda los números en formato E.164, un signo más seguido del código de país y el número, y rechaza cualquier otra cosa antes de llamar a la API.
  • OneSignal Verify es la alternativa gestionada. Genera y comprueba los códigos por ti. Clean Beans crea los suyos para mostrar el flujo completo.
Configuración del panel. Completa la configuración de SMS y elige un remitente predeterminado que pueda llegar a los países en los que están tus usuarios.

Contraseñas de un solo uso

OneSignal Verify y cómo crear tu propia solución.

Opt-in y recopilación de SMS

Requisitos de consentimiento y avisos.

Referencia de la API de SMS

Todos los parámetros de SMS.