# Códigos de verificación (OTP) por WhatsApp

Sirve para el registro, el inicio de sesión o la confirmación de un pago en tu
plataforma: tu usuario escribe su número, le llega un código por WhatsApp y lo
escribe de vuelta en tu pantalla.

## Quién hace qué

Es lo primero que hay que tener claro, porque define todo lo demás:

| Paso | Lo hace |
|---|---|
| Generar el código (por ejemplo, 6 dígitos al azar) | **Tu backend** |
| Guardarlo con su vencimiento y sus intentos | **Tu backend** |
| Entregarlo por WhatsApp con la plantilla de autenticación | **Meteor** |
| Comparar lo que la persona escribió con lo que guardaste | **Tu backend** |

Meteor **no genera ni valida** el código, y **no lo guarda**: en el chat del
contacto queda solo la nota «Código de verificación enviado por WhatsApp», nunca
el código. Así el código vive en un solo lugar, el tuyo.

## Lo que necesitas

- Una **API key** con los scopes `channels:read`, `channels:send` y
  `contacts:write` (ver [Autenticación](autenticacion.html)).
- Un **canal de WhatsApp** conectado a tu workspace.
- Una **plantilla de categoría `AUTHENTICATION`** aprobada por Meta, en la misma
  cuenta de WhatsApp (WABA) de la línea que envía. Con una plantilla de otra
  categoría el envío se rechaza, aunque el texto diga «tu código es…».

El envío de OTP está disponible para todas las cuentas. Meteor puede apagarlo en
una cuenta puntual; si te pasa, la respuesta es `authentication_send_not_enabled`
y hay que escribir a soporte.

## 1. Crear la plantilla de autenticación (una sola vez)

Meta fija la forma de estas plantillas: el texto lo pone Meta en el idioma de la
plantilla («*123456* es tu código de verificación»). Tú solo eliges si lleva el
aviso de seguridad y cuántos minutos dura el código.

```ts
const canales = await met.channels.list();
const whatsapp = canales.find((c) => c.type === 'whatsapp')!;

await met.channels.createTemplate(whatsapp.id, {
  name: 'codigo_verificacion',
  language: 'es',
  category: 'AUTHENTICATION',
  components: [
    // Sin `text`: Meta rechaza un BODY con texto en esta categoría.
    { type: 'BODY', add_security_recommendation: true },
    { type: 'FOOTER', code_expiration_minutes: 10 },
    // Botón para copiar el código. Sin `text`: Meta pone «Copiar código».
    { type: 'BUTTONS', buttons: [{ type: 'OTP', otp_type: 'COPY_CODE' }] },
  ],
});
```

La plantilla nace en revisión (`PENDING`). Antes de usarla, confirma que quedó
`APPROVED` y de qué cuenta es:

```ts
const { data } = await met.channels.templates(whatsapp.id, { name: 'codigo_verificacion' });
const otp = data.find((t) => t.name === 'codigo_verificacion' && t.language === 'es');
// otp.status === 'APPROVED' && otp.category === 'AUTHENTICATION'
```

Si tienes varias cuentas de WhatsApp en el canal, la plantilla tiene que estar
aprobada **en la cuenta de la línea que envía** (ver
[Plantillas de WhatsApp por API](plantillas-whatsapp.html)).

## 2. El contacto tiene que existir

El código va a un **contacto** de tu workspace, no a un número suelto. Si la
persona es nueva, créalo primero con su número:

```ts
const contacto = await met.contacts.create({ name: 'Ana Pérez', phone: '+573001234567' });
```

Un contacto bloqueado en Meteor no recibe códigos.

## 3. Generar el código y enviarlo

```ts
import { randomInt } from 'node:crypto';

const codigo = String(randomInt(0, 1_000_000)).padStart(6, '0');
await guardarCodigo(usuario.id, codigo, { venceEn: '10m', intentos: 0 }); // tu base

await met.channels.whatsapp.sendTemplate(whatsapp.id, {
  contact_id: contacto.id,
  template_name: 'codigo_verificacion',
  language: 'es',
  purpose: 'authentication',
  components: [
    { type: 'body', parameters: [{ type: 'text', text: codigo }] },
    // El botón de copiar lleva el MISMO código.
    { type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: codigo }] },
  ],
});
```

Con `purpose: 'authentication'` Meteor verifica, antes de mandar nada, que la
plantilla sea de autenticación, que esté aprobada en la cuenta de la línea y que
el contacto sea de tu workspace. Si algo no cuadra, no se envía ningún mensaje.

Este envío **no toca la atención del chat**: no reactiva al Met ni cambia la
asignación de la conversación.

> **Probar sin enviar:** `dry_run: true` valida la plantilla, la línea y el
> contacto y devuelve el destinatario, sin llamar a Meta. La respuesta nunca trae
> el código.

## 4. Validar el código

Cuando la persona escribe el código en tu pantalla, lo comparas tú con lo que
guardaste. Unas reglas que conviene respetar:

- **Vencimiento corto:** entre 5 y 10 minutos, igual al que pusiste en la plantilla.
- **Pocos intentos:** 3 a 5; después, un código nuevo.
- **Un solo uso:** al validarlo, bórralo.
- **Compara en tiempo constante** (`crypto.timingSafeEqual`) para no filtrar
  pistas por el tiempo de respuesta.
- **Limita los reenvíos** por número y por hora: cada envío es una conversación
  de autenticación que Meta cobra.

## Errores

| Código | HTTP | Qué pasó | Qué hacer |
|---|---|---|---|
| `authentication_send_not_enabled` | 403 | El envío de OTP está apagado en tu cuenta | Escribir a soporte |
| `authentication_template_required` | 403 | La plantilla no existe con ese nombre e idioma, no está aprobada o no es `AUTHENTICATION` en la cuenta de la línea | Revisar `channels.templates` |
| `authentication_template_unverifiable` | 503 | No se pudo confirmar la plantilla o la cuenta con Meta | Reintentar en unos segundos |
| `authentication_contact_unverifiable` | 503 | No se pudo verificar el contacto | Reintentar |
| — | 404 | El contacto no es de tu workspace | Crear el contacto (paso 2) |
| `authentication_provider_rejected` | 400 | WhatsApp no aceptó el envío; trae `provider_code` | Ver el código de Meta (por ejemplo 131026: el número no tiene WhatsApp) |

Para reintentos sin duplicar el envío, usa una clave de idempotencia
(ver [Errores e idempotencia](errores-e-idempotencia.html)), y revisa los topes de
tu plan en [Límites](limites.html).
