# Conectar el chatbot a WhatsApp Business (Meta Cloud API)

El mismo cerebro del bot (catálogo, pedidos, devoluciones, idiomas, seguridad)
contesta también por WhatsApp. Gratis: las conversaciones de servicio (el
cliente te escribe y tú respondes en 24h) no cuestan nada.

**Lo que ya está hecho en el backend:** el webhook `/whatsapp/webhook`, el envío
de respuestas, multi-tienda (cada número de WhatsApp → su tienda), sesiones por
teléfono y firma de seguridad. Solo falta el papeleo de Meta (esta guía).

---

## Parte 1 — Crear la app en Meta (una sola vez, ~20 min)

1. Entra en **https://developers.facebook.com** con tu cuenta de Facebook/Meta.
2. **My Apps → Create App** → tipo **Business** → ponle nombre (ej. "Flexigo Bot").
3. En el panel de la app, busca **WhatsApp** y pulsa **Set up**.
   - Meta te crea un **número de prueba** gratis para empezar (sirve para probar ya).
4. Apunta del panel **WhatsApp → API Setup**:
   - **Phone number ID** (un número largo, NO es el teléfono) → se pega en el admin del bot.
   - **Temporary access token** (caduca en 24h; para producción ver Parte 4).

## Parte 2 — Configurar el webhook

1. En la app de Meta: **WhatsApp → Configuration → Webhook → Edit**.
2. Rellena:
   - **Callback URL:** `https://victor34593993-flexigo-support-bot.hf.space/whatsapp/webhook`
   - **Verify token:** el valor de `WHATSAPP_VERIFY_TOKEN` (ya está puesto como
     secret en el Space; te lo di al desplegar — guárdalo).
3. Pulsa **Verify and save** (Meta llama al webhook; debe poner la marca verde).
4. En **Webhook fields**, pulsa **Manage** y suscríbete a **messages** (solo ese).

## Parte 3 — Conectar la tienda en el admin del bot

1. Abre el admin del bot → elige la tienda (tenant).
2. Sección **WhatsApp (Meta Cloud API)**:
   - **Phone Number ID:** el de la Parte 1.
   - **Access Token:** el token (se guarda cifrado).
3. Guardar. **Listo:** escribe al número de WhatsApp y el bot contesta.

> Multi-tienda: cada tienda con su propio número → su propio Phone Number ID y
> su token en su tenant. El bot nunca mezcla datos entre tiendas.

## Parte 4 — Pasar a producción (cuando funcione la prueba)

1. **Número real:** WhatsApp → API Setup → **Add phone number** (el número NO
   puede estar ya registrado en la app normal de WhatsApp; usa uno nuevo o da
   de baja el actual primero).
2. **Token permanente** (el temporal caduca a las 24h):
   - **Business Settings → Users → System users → Add** (rol Admin).
   - Asigna la app al system user → **Generate token** → permisos
     `whatsapp_business_messaging` + `whatsapp_business_management` → sin caducidad.
   - Pega ese token en el admin del bot (campo Access Token de la tienda).
3. **App secret** (recomendado, valida que los webhooks vienen de Meta):
   - App Settings → Basic → **App Secret** → ponlo como secret
     `WHATSAPP_APP_SECRET` en el HF Space. A partir de ahí el webhook rechaza
     cualquier petición que no firme Meta.
4. **Verificar el negocio** (Business Manager → Security Centre): sin verificar
   puedes hablar con hasta 5 números (modo dev); verificado, sin límite de
   clientes que te escriban.

## Límites y costes (resumen honesto)

- **Cliente te escribe → tú respondes (24h):** GRATIS, ilimitado. Es el caso del bot.
- **Tú inicias conversación (plantillas/marketing):** de pago — el bot NO lo hace.
- El número de prueba de Meta solo habla con hasta 5 números que registres tú
  (perfecto para probar). El salto a número real es la Parte 4.

## Alta de un CLIENTE nuevo (1 clic desde tu admin)

El webhook es global (configurado una vez): **no se toca nunca más**. Para cada
tienda nueva:

1. **Registra su número** en tu WhatsApp Manager (Business Manager → WhatsApp
   Manager → Añadir número). El cliente solo te pasa el código SMS que le llega.
   Tu negocio verificado permite hasta 20 números; cada cliente puede tener su
   propio WABA bajo tu portfolio (su nombre de empresa sale en WhatsApp).
2. En el **admin del bot** → su tienda → sección WhatsApp → pega **WABA ID** +
   **Phone Number ID** (+ token si esa tienda usa uno propio; vacío = el global)
   → **Conectar número**. El backend suscribe el WABA, valida el número y lo
   deja contestando. Eso es todo.

> Con un **token permanente de system user** de TU Business Manager (Parte 4)
> configurado como global, las tiendas bajo tu portfolio no necesitan token
> propio: el alta es literalmente pegar 2 IDs y pulsar un botón.

### Futuro: autoservicio total (Embedded Signup)

Para que el cliente se conecte SOLO (botón "Conectar WhatsApp" → login con su
Facebook → listo, como Twilio/360dialog): requiere **Verificación de acceso**
(proveedor de tecnología; Configuración básica → Verificación de acceso, ~5
días) + acceso avanzado a `whatsapp_business_management` y
`whatsapp_business_messaging` (App Review). Cuando Meta lo apruebe, se monta el
botón sobre el mismo endpoint de conexión que ya existe.

## Problemas típicos

- **"Verify and save" falla:** el verify token no coincide con el del Space, o
  el Space estaba dormido (ábrelo primero: `/healthz`).
- **El bot no contesta:** ¿token caducado (el temporal dura 24h)? ¿Phone Number
  ID pegado en la tienda correcta? Mira los logs del Space.
- **Contesta a unos números y a otros no:** estás en modo prueba (5 números
  permitidos) o el negocio no está verificado.