GUIA_WHATSAPP.md

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.