# 09 · Alta de números y onboarding de clientes

Para que un cliente use WhatsApp tiene que **conectar su número a su propia cuenta de WhatsApp Business** y autorizar a la plataforma. El gateway usa **Embedded Signup v4** de Meta: el cliente lo hace en una ventana de Meta, sin que vosotros veáis sus credenciales ni sus datos de pago.

> **¿El número ya se usa en la app WhatsApp Business y no queréis dejar de usarlo?** Hay un alta específica, la **coexistencia**: [14 · La cuenta de Meta y la coexistencia](14-cuenta-de-meta-y-coexistencia.md). En la pantalla de alta es el botón «Uso este número en la app WhatsApp Business».

## Lo que ocurre, de principio a fin

```
Cliente (admin del tenant)           wa-gateway                          Meta
   │ pulsa "Conectar un número" ──▶ crea una sesión de alta (state de 30 min)
   │ ◀── ventana de Meta ───────────────────────────────────────────────▶ inicia sesión, elige o crea su cuenta,
   │                                                                     verifica el número, acepta condiciones
   │ ◀── code + waba_id + phone_number_id
   │ ──▶ complete ──▶ canjea el code AL INSTANTE (caduca a los 30 s) ───▶ token del cliente (se guarda cifrado)
   │                  worker: suscribir webhooks ─▶ registrar el número ─▶ leer estado ─▶ importar plantillas
   │ ◀── evento whatsapp.number.connected                                 (pago: awaiting_payment)
   │ añade su tarjeta en WhatsApp Manager ───────────────────────────────▶ primer envío aceptado → active
```

La pantalla `settings` → **Conectar un número** lo hace entero ([06](06-ui-embebible.md)). Si preferís orquestarlo desde vuestro backend, la API es `POST /v1/whatsapp/signup-sessions` → (Embedded Signup en una ventana propia) → `POST …/{id}/complete` → `GET …/{id}` hasta `completed`.

| Paso de la sesión (`step`) | Significado |
| --- | --- |
| `created` | Esperando a que el cliente termine en Meta (caduca a los 30 min → `expired`) |
| `code_exchanged` → `webhooks_subscribed` → `phone_registered` | El worker va avanzando; cada paso se reintenta solo ante fallos transitorios |
| `completed` | Conectado. `number_id` y `payment_status` informados |
| `failed` | `error` explica el paso y el motivo; llega `whatsapp.signup.failed`. Hay que **repetir el alta**: el `code` es de un solo uso |

## Lo que debe hacer el cliente — en Meta

1. **Tener un Business Portfolio (Meta Business Manager)** de su empresa, o dejar que Meta lo cree durante el alta. Debe ser el de la **empresa**, no uno personal.
2. **Verificar su negocio** (nombre legal, dirección, documento, web/correo corporativo). Puede tardar de horas a unos días. Sin verificar, el límite diario es bajo (empieza en 250 destinatarios únicos cada 24 h); verificarlo y usarlo bien lo va subiendo.
3. **Elegir el número**:
   - Un número **nuevo**: se verifica por SMS o llamada durante el alta.
   - Un número que ya usa en la **app móvil de WhatsApp Business**: con la **coexistencia** ([14](14-cuenta-de-meta-y-coexistencia.md)) sigue funcionando en el móvil y se conecta además a la API. Sin ella (alta «número nuevo o solo para la API»), dejaría de funcionar en el móvil.
   - El número **no puede** estar ya registrado en la API de otro proveedor.
4. **Elegir el nombre visible** (*display name*): es lo que verán sus clientes. Meta lo revisa (hasta 24–48 h) y debe corresponder con su marca.
5. **Aceptar las condiciones** de WhatsApp Business Platform y **autorizar a la plataforma** a gestionar su cuenta (lo hace él mismo en la ventana de Meta).
6. **Añadir su método de pago** en *WhatsApp Manager → Configuración de la cuenta → Facturación* (`https://business.facebook.com/wa/manage/home/`). **Meta le factura a él, con su tarjeta**. Hasta hacerlo, la cuenta queda en `awaiting_payment` y no podrá enviar plantillas fuera de las pruebas. La pantalla `settings` muestra un aviso con el enlace.

## Lo que debe hacer el cliente — en vuestra plataforma

1. Que **administración le dé de alta** (tenant, licencia del módulo y app habilitada): [11](11-administracion.md).
2. **Conectar el número** (arriba).
3. **Crear y enviar a aprobación sus plantillas** (o activar las de la biblioteca): [04](04-plantillas.md).
4. **Dar de alta a sus agentes** o dejar que se creen al entrar por la pantalla de chat: [06](06-ui-embebible.md).
5. **Configurar consentimiento y bajas**: [07](07-conversaciones-y-contactos.md).
6. Opcional: fijar la **alerta de gasto mensual**: [08](08-licencias-limites-y-costes.md).

## Estados que conviene mostrar al cliente

| Dónde | Valor | Mensaje sugerido |
| --- | --- | --- |
| `GET /v1/whatsapp/account` → `business_verification_status` | `not_verified` / `verified` | «Verifica tu negocio en Meta para ampliar tus límites» |
| `payment_status` | `awaiting_payment` | «Falta añadir tu tarjeta en WhatsApp Manager» (con enlace) |
| `payment_status` | `blocked` | «Meta ha bloqueado tus envíos por un problema de pago» |
| `status` | `restricted` | «Meta ha restringido tu cuenta; revisa su estado» (evento `whatsapp.account.restricted`; con `reason: credential_invalid` hay que **repetir el alta**) |
| `GET /v1/numbers` → `quality_rating` | `GREEN` / `YELLOW` / `RED` | Con `RED`, riesgo de bloqueo: revisar el contenido y el consentimiento |
| `messaging_limit` | `TIER_250`, `TIER_1K`… | Destinatarios únicos cada 24 h |
| `name_status` | `PENDING_REVIEW`, `APPROVED`, `DECLINED` | Estado del nombre visible |

## Problemas frecuentes

| Síntoma | Causa y solución |
| --- | --- |
| El alta devuelve `409 … ya está conectada a otro cliente` | Esa cuenta o ese número ya pertenece a otro tenant. Una cuenta de WhatsApp solo puede estar en un cliente |
| `failed` con `code` inválido o caducado | Tardó más de 30 s entre Meta y el gateway, o se reutilizó el `code`. Repetir el alta |
| `403 license_limit_reached` (`max_numbers`) | La licencia permite menos números de los que intenta conectar |
| El número queda `pending`/`flagged` | Meta no ha terminado de verificarlo o lo ha marcado; `POST /v1/numbers/{id}/refresh` lo relee |
| Los envíos fallan con `131042` | Falta o falla la tarjeta del cliente en Meta ([08](08-licencias-limites-y-costes.md)) |
| Los envíos fallan con `131047` | La ventana de 24 h se cerró; usar una plantilla |
| `whatsapp.account.restricted` con `credential_invalid` | El token del cliente se revocó (cambió permisos o sacó a la plataforma de su cuenta). Repetir el alta |

## Texto para entregar al cliente

> **Conectar tu WhatsApp**
> 1. En la pantalla de Configuración de la aplicación, pulsa **Conectar un número**.
> 2. En la ventana de Meta, inicia sesión con tu cuenta de Facebook de empresa. Elige o crea tu cuenta de WhatsApp Business, introduce el número y verifícalo con el código que recibirás. Si ese número está en la app de WhatsApp Business del móvil, dejará de funcionar allí.
> 3. Elige el nombre que verán tus clientes y acepta las condiciones. Meta lo revisará en uno o dos días.
> 4. Entra en **WhatsApp Manager → Configuración de la cuenta → Facturación** y añade tu tarjeta. Meta cobrará directamente los mensajes a esa tarjeta; la aplicación no ve tus datos de pago.
> 5. Vuelve a la aplicación: cuando veas «Número conectado» y «Pago activo», ya puedes enviar.

La versión maquetada de esta guía, con el detalle de cada pantalla de Meta, es el documento *Guía de conexión a WhatsApp Business para clientes*.