> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App de ejemplo: códigos de verificación e invitaciones por SMS

> Cómo la app de ejemplo Clean Beans verifica números de teléfono con códigos de un solo uso e invita a personas por SMS o email con OneSignal.

Esta página forma parte de [App de ejemplo: una integración completa de OneSignal](https://documentation.onesignal.com/docs/es/example-full-integration-overview.md), 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.

| Mensaje | Se envía a | Disparador |
| - | - | - |
| Código de verificación | El número que acaba de introducir un usuario que ha iniciado sesión | Llamada desde la app |
| Invitación al hogar | Un número de teléfono o una dirección de email de alguien sin cuenta | Llamada desde 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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-phone-verification.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=ae377258019c7454d600dc86bb722cce)

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.

```typescript supabase/functions/_shared/otp.ts theme={null}
export function generateCode(): string {
  const limit = 4_000_000_000; // a multiple of 1,000,000 below 2^32, so no code is more likely than another
  const buf = new Uint32Array(1);
  do {
    crypto.getRandomValues(buf);
  } while (buf[0] >= limit);
  return String(buf[0] % 1_000_000).padStart(6, '0');
}

export async function hashCode(secret: string, userId: string, phone: string, code: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${userId}:${phone}:${code}`));
  return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, '0')).join('');
}
```

```typescript supabase/functions/send-otp/index.ts theme={null}
const { data: inserted, error: insertErr } = await supabase
  .from('phone_otp_codes')
  .insert({
    user_id: user.id,
    phone,
    code_hash: codeHash,
    expires_at: new Date(now.getTime() + OTP_TTL_MINUTES * 60_000).toISOString(),
  })
  .select('id')
  .single();
```

**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.

```typescript supabase/functions/send-otp/index.ts theme={null}
const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  target_channel: 'sms',
  // Targets a raw phone number. OneSignal creates an SMS subscription
  // for it if one does not exist yet.
  include_phone_numbers: [phone],
  ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
  name: 'Phone verification code',
  contents: {
    en: `Your Clean Beans verification code is ${code}. It expires in ${OTP_TTL_MINUTES} minutes.`,
  },
};
```

**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.

```typescript supabase/functions/verify-otp/index.ts theme={null}
const submittedHash = await hashCode(OTP_HASH_SECRET, user.id, phone, code);

if (!safeEqual(submittedHash, row.code_hash)) {
  const attempts = row.attempts + 1;
  await supabase.from('phone_otp_codes').update({ attempts }).eq('id', row.id);

  const left = OTP_MAX_ATTEMPTS - attempts;
  return jsonResponse({
    error: 'invalid_code',
    message: left > 0
      ? `That code is not right. ${left} ${left === 1 ? 'attempt' : 'attempts'} left.`
      : 'Too many wrong attempts. Request a new code.',
    attemptsLeft: Math.max(left, 0),
  }, 400);
}
```

**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.

```typescript src/lib/phone.ts theme={null}
export async function confirmPhoneCode(phone: string, code: string): Promise<void> {
  await callFunction('verify-otp', { body: { phone, code } });
  OneSignal.User.addSms(phone);
}
```

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.

```typescript src/lib/phone.ts theme={null}
export async function syncOneSignalSms(): Promise<void> {
  try {
    const phone = await loadVerifiedPhone();
    if (phone) {
      OneSignal.User.addSms(phone);
      console.log('[phone] SMS subscription synced');
    }
  } catch (e) {
    console.warn('[phone] syncOneSignalSms error:', e);
  }
}
```

> [!NOTE]
>
> 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.

| Regla | Valor |
| - | - |
| Validez del código | 10 minutos |
| Intentos fallidos permitidos | 5 |
| Espera antes de reenviar | 30 segundos |
| Códigos por usuario | 3 cada 10 minutos |
| Usos por código | Uno. Un código nuevo sustituye a cualquier anterior |

```typescript supabase/functions/send-otp/index.ts theme={null}
const MAX_CODES_PER_WINDOW = 3;
const WINDOW_MINUTES = 10;
const RESEND_COOLDOWN_SECONDS = 30;
```

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.

```sql supabase/migrations/028_phone_verification_and_invites.sql theme={null}
create table if not exists public.user_phones (
  user_id     uuid primary key references public.profiles(id) on delete cascade,
  phone       text not null,                       -- E.164, e.g. +14155551234
  verified_at timestamptz not null default now()
);
```

## Pedir el consentimiento donde se introduce el número \\

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.

```tsx src/components/PhoneVerificationCard.tsx theme={null}
{/* Consent disclosure: must sit next to the phone field */}
<Text style={styles.disclosure}>
  Enter your mobile number to receive verification codes by text message from Clean Beans.
  Msg & data rates may apply. Reply STOP to opt out.
</Text>
```

## 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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-invitation.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=78d087c22898bc9876dbdd1f90c56033)

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.

```typescript supabase/functions/send-invite/index.ts theme={null}
const joinUrl = `${JOIN_URL}?code=${encodeURIComponent(household.invite_code)}`;

const onesignalPayload: Record<string, unknown> = channel === 'sms'
  ? {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'sms',
      // Raw phone number: OneSignal creates an SMS subscription if needed
      include_phone_numbers: [contact],
      ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
      name: 'Household invitation (SMS)',
      contents: {
        en: `${inviterName} invited you to join "${householdName}" on Clean Beans, the cleaning rota app. Join: ${joinUrl} Reply STOP to opt out.`,
      },
    }
  : {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'email',
      // Raw email address: OneSignal creates an email subscription if needed
      email_to: [contact],
      name: 'Household invitation (email)',
      email_subject: `${inviterName} invited you to Clean Beans`,
      email_preheader: `Join "${householdName}" and share the cleaning.`,
      email_body: buildInviteEmail(inviterName, householdName, joinUrl, household.invite_code),
      // Keep the join link exactly as written. Click tracking would wrap
      // it in a redirect, and it would stop opening the app directly.
      disable_email_click_tracking: true,
    };
```

El enlace es un Universal Link, configurado en [Abrir la app desde enlaces web normales](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links). 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.

> [!WARNING]
>
> 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](https://documentation.onesignal.com/docs/es/sms-setup.md) y elige un remitente predeterminado que pueda llegar a los países en los que están tus usuarios.

> [card] [Contraseñas de un solo uso](https://documentation.onesignal.com/docs/es/sms-verify.md)
>
> OneSignal Verify y cómo crear tu propia solución.

> [card] [Opt-in y recopilación de SMS](https://documentation.onesignal.com/docs/es/sms-opt-in-and-collection.md)
>
> Requisitos de consentimiento y avisos.

> [card] [Referencia de la API de SMS](https://documentation.onesignal.com/reference/sms.md)
>
> Todos los parámetros de SMS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.