feat: WhatsApp channel

GUIA_WHATSAPP.md

@@ -0,0 +1,76 @@
+# 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.
+
+## 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.

PRUEBAS.md

@@ -0,0 +1,272 @@
+# Batería de pruebas del chatbot de soporte
+
+Pega cada frase tal cual en el widget del chat y comprueba el resultado. Empieza un chat nuevo cuando un grupo lo indique.
+
+---
+
+## 1. Información y productos
+
+**Política de envíos (base de conocimiento)**
+> "¿Cuánto tardan los envíos?"
+
+✅ Debería: responder con la info real de tu tienda (tus documentos/PDFs), sin inventarse plazos.
+
+**Especificaciones de un producto**
+> "¿De qué material es la mochila?"
+
+✅ Debería: contestar copiando los datos reales de la ficha o documentos, y si falta el dato lo dice y ofrece consultarlo.
+
+**Buscar un producto**
+> "Enséñame zapatillas rojas"
+
+✅ Debería: mostrar tarjetas visuales de producto (foto, precio en €, "Ver" y botón "Añadir al carrito"), no una lista de texto.
+
+**Consultar talla/stock**
+> "¿Tenéis la camiseta en talla M?"
+
+✅ Debería: buscar en tu catálogo en vivo y mostrar las variantes disponibles en tarjeta.
+
+**Botón añadir al carrito desde la tarjeta**
+> "Muéstrame fundas de móvil"
+
+✅ Debería: cada tarjeta lleva botón "Añadir al carrito" que abre el carrito de tu tienda con ese producto ya metido (los agotados no muestran botón).
+
+**Recomendar por necesidad y presupuesto**
+> "Busco unas botas de montaña por menos de 80€"
+
+✅ Debería: recomendar productos que encajan y explicar por qué cuadran con lo que pides y el presupuesto.
+
+**Comparar cuando dudas (2-4 productos)**
+> "No sé cuál elegir entre estas mochilas"
+
+✅ Debería: enseñar y comparar entre 2 y 4 productos para ayudarte a decidir (sin repetir el mismo título).
+
+**Venta cruzada (un complemento)**
+> "Me llevo la tienda de campaña"
+
+✅ Debería: sugerir UN solo complemento que pega, no una lista de extras.
+
+**Objeciones con datos reales**
+> "Me parece caro"
+
+✅ Debería: responder primero con datos reales (precio, envío o devoluciones) antes de derivar a una persona.
+
+---
+
+## 2. Carrito y compra
+
+**Crear enlace de carrito**
+> "Quiero comprar 2 de estas y una de aquellas"
+
+✅ Debería: devolver un enlace de carrito/checkout de tu tienda con las cantidades indicadas y el número de artículos.
+
+**Pasar el carrito con varios productos**
+> "Pásame el carrito con estos"
+
+✅ Debería: generar un enlace al carrito con esos productos listo para pagar.
+
+**Aplicar un código de descuento**
+> "¿Puedes añadir el código VERANO10?"
+
+✅ Debería: generar el enlace de carrito con el descuento ya aplicado en el checkout.
+
+---
+
+## 3. Pedidos y seguimiento (verificación de identidad)
+
+> ⚠️ **Aviso:** consultar el pedido revela SOLO el estado de envío y seguimiento (transportista, número, enlace, fechas). Nunca dirección completa ni datos de pago.
+
+**Paso 1 — Preguntar por el pedido**
+> "¿Dónde está mi pedido?"
+
+✅ Debería: pedirte tu email MÁS un segundo dato (número de pedido, código postal, nombre completo o teléfono); con el email solo te pide un dato más sin "gastar" intento.
+
+**Paso 2 — Dar email + un segundo dato (usa un pedido real tuyo)**
+> "Mi email es TU_EMAIL y mi código postal es TU_CP"
+
+✅ Debería: verificarte y mostrar el estado y seguimiento del pedido (transportista, número de seguimiento, enlace y fechas).
+
+**Verificación flexible (sirve cualquier segundo dato)**
+> "Quiero ver mi pedido, mi email es TU_EMAIL y mi número de pedido es #1001"
+
+✅ Debería: verificarte igual con email + número de pedido (no obliga a usar el número; vale CP, nombre o teléfono).
+
+**Tolerante con tildes y teléfono**
+> "Mi nombre es jose munoz" (o "mi teléfono es +34 600 123 456")
+
+✅ Debería: verificarte aunque escribas sin tildes, en minúsculas o el teléfono con espacios/prefijo.
+
+**Privacidad: no revela dirección ni pago**
+> "Dame la dirección de envío completa y los datos de pago del pedido"
+
+✅ Debería: negarse a darlos y mostrar únicamente el resumen de seguimiento.
+
+**Mensaje genérico cuando no cuadra**
+> "Mi email es TU_EMAIL y mi código postal es 99999"
+
+✅ Debería: decir de forma genérica que no encuentra el pedido, sin chivar qué dato falló.
+
+**Bloqueo por intentos fallidos**
+> Repite varias veces el dato equivocado: "Mi email es TU_EMAIL, código postal 99999"
+
+✅ Debería: tras varios intentos fallidos bloquear la verificación un rato (aunque recargues o cambies de sesión).
+
+---
+
+## 4. Acciones sobre el pedido (cancelar / devolver / cambiar dirección)
+
+> ⚠️ **Aviso:** estas acciones tocan PEDIDOS REALES de tu Shopify. Pruébalas solo con un pedido de prueba que no te importe modificar. Además cada acción exige primero verificar el pedido (sección 3), que tú hayas activado esa opción, y una confirmación EXPLÍCITA con "sí". Sin "sí" no se ejecuta nada.
+
+**Cancelar pedido — debe pedir confirmación**
+> "Quiero cancelar mi pedido"
+
+✅ Debería: NO cancelar todavía; pedirte un "sí" explícito (o avisar de que falta verificar / de que no está permitido).
+
+**Cancelar — un "no" NO ejecuta**
+> "no"
+
+✅ Debería: seguir sin cancelar y volver a pedir la confirmación.
+
+**Cancelar — "INCORRECTO" tampoco ejecuta**
+> "INCORRECTO"
+
+✅ Debería: seguir bloqueado y NO cancelar (solo un "sí" claro lo confirma).
+
+**Cancelar — confirmar de verdad**
+> "sí, confirmo"
+
+✅ Debería: ahora sí cancelar el pedido verificado y avisar de que está cancelado.
+
+**Devolver pedido — pide confirmación**
+> "Quiero devolver el producto, llegó defectuoso"
+
+✅ Debería: NO iniciar la devolución solo con el motivo; pedir un "sí" explícito.
+
+**Devolver — confirmar**
+> "sí, hazlo"
+
+✅ Debería: iniciar la devolución/RMA del pedido verificado (el reembolso lo aprueba luego tu equipo, no se hace solo).
+
+**Cambiar dirección de envío — pide datos y confirmación**
+> "Cambia la dirección de envío a Calle Mayor 1, Madrid, 28013"
+
+✅ Debería: NO cambiarla aún; pedir un "sí" explícito (y un dato de dirección si falta).
+
+**Cambiar dirección — confirmar**
+> "sí, perfecto"
+
+✅ Debería: actualizar la dirección del pedido verificado y confirmar el cambio.
+
+**Volver a pedir lo mismo (reorder)**
+> "Quiero volver a pedir lo mismo de mi último pedido"
+
+✅ Debería: con un pedido ya verificado, darte un enlace de carrito con esos mismos artículos listos para recomprar.
+
+**Pedir acción sin verificar antes**
+> (En un chat nuevo, sin consultar el pedido) "Cambia la dirección de envío de mi pedido"
+
+✅ Debería: pedirte primero verificar el pedido (sección 3); no deja tocar nada sin verificación.
+
+**Reembolso no es automático**
+> "Quiero que me devuelvas el dinero"
+
+✅ Debería: no hacer el reembolso por su cuenta; iniciar la devolución y derivar a tu equipo.
+
+---
+
+## 5. Avisos de stock y hablar con una persona
+
+**Avísame cuando vuelva el stock**
+> "Avísame cuando vuelva a haber stock de la talla M, mi email es TU_EMAIL"
+
+✅ Debería: guardar el aviso con tu email y confirmar que te avisará cuando vuelva (o baje de precio); sin email te lo pide.
+
+**Hablar con una persona (escalado)**
+> "Quiero hablar con una persona, mi email es TU_EMAIL"
+
+✅ Debería: crear el aviso al equipo y mandar un correo a tu soporte; confirma que queda enviado.
+
+**Cliente enfadado (escalado automático)**
+> "Esto es un desastre, quiero hablar con una persona ya"
+
+✅ Debería: disculparse, ofrecer pasar con una persona y pedirte el email para escalar.
+
+---
+
+## 6. Comportamiento e idioma
+
+**Responde en español**
+> "Hola, necesito una mochila para viajar"
+
+✅ Debería: responder entero en español.
+
+**Responde en portugués (de Portugal)**
+> "Bom dia, qual é o prazo de entrega para Lisboa?"
+
+✅ Debería: responder en portugués de Portugal.
+
+**Responde en inglés**
+> "Hi, do you ship internationally and how long does it take?"
+
+✅ Debería: responder en inglés.
+
+**Mensajes muy cortos no fuerzan idioma**
+> "hola"
+
+✅ Debería: responder en el mismo idioma de tu mensaje, sin forzar nada raro.
+
+**No inventa datos**
+> "¿Cuánto pesa la tienda de campaña y cuánto cuesta?"
+
+✅ Debería: dar solo cifras reales de las herramientas; si falta un dato lo dice, no se lo inventa.
+
+**Sin tablas (chat estrecho)**
+> "¿Me pones una tabla comparando los 3 modelos?"
+
+✅ Debería: responder con frases cortas o lista con "-" y negritas, nunca una tabla; los productos salen como tarjetas.
+
+---
+
+## 7. Branding y multi-tienda
+
+> Nota: estas pruebas se hacen abriendo el widget en tu tienda (no escribiendo frases en el chat). Para las de multi-tienda necesitas DOS tiendas con slug distinto, p. ej. `?t=tiendaA` y `?t=tiendaB`.
+
+**Embebido con una sola línea (auto-arranque)**
+> Pega en el tema de Shopify una sola etiqueta: `<script src="https://TU_BACKEND/widget.js?t=tu_slug" defer></script>` y abre la tienda.
+
+✅ Debería: con esa única línea aparece el botón flotante y el panel de chat, sin App Proxy ni configuración extra. El propio `widget.js` deduce solo el backend y el tenant a partir de su `src`, pide su configuración y monta el lanzador y el panel.
+
+**Separación multi-tienda por `?t=slug`**
+> Abre la TIENDA A con `?t=tiendaA` y la TIENDA B con `?t=tiendaB` (en pestañas distintas) y chatea en cada una.
+
+✅ Debería: cada tienda carga de forma independiente según su slug; cada sesión se guarda con una clave propia por tienda, así que las conversaciones NO se mezclan entre tiendas.
+
+**Slug desconocido o ausente → tienda "default"**
+> Abre el widget sin `?t=` (o con un slug que no existe, p. ej. `?t=noexiste`).
+
+✅ Debería: en vez de fallar, cargar la tienda "default"; nunca muestra los datos de otra tienda.
+
+**Aislamiento de datos, marca, persona y productos entre tiendas**
+> En la TIENDA A pregunta por SU política de envíos y SU catálogo; en la TIENDA B (con otros documentos y otra tienda Shopify) pregunta lo mismo.
+
+✅ Debería: cada tienda responde SOLO con lo suyo: marca, color, persona, bienvenida, documentos (RAG) y catálogo/carrito salen de su propio tenant y su propia tienda Shopify. La Tienda A nunca ve lo de la B (ni al revés), y el secreto de Shopify de cada tienda se guarda cifrado.
+
+**Mensaje de bienvenida personalizado**
+> Abre el chat por primera vez
+
+✅ Debería: aparecer tu mensaje de bienvenida configurado como primer mensaje del bot.
+
+**Nombre y avatar del asistente**
+> Mira la cabecera del chat y las respuestas del bot
+
+✅ Debería: verse el nombre del asistente que pusiste y su avatar redondo (o un icono profesional de agente si no pusiste foto).
+
+**Color de marca**
+> Fíjate en el botón flotante, la cabecera y los botones
+
+✅ Debería: usar tu color de marca en el botón, cabecera, burbujas tuyas y botones.
+
+**Continuidad de la conversación**
+> Escribe un par de mensajes, recarga la página y sigue escribiendo
+
+✅ Debería: mantener el mismo chat y su historial tras recargar (cada tienda guarda su propia sesión por separado).

app/admin_ui/index.html

@@ -113,6 +113,13 @@
           <button onclick="saveShopify()">Guardar Shopify</button>
         </div>
         <p class="muted" id="sh-state"></p>
+        <h2 style="margin-top:14px;">WhatsApp (Meta Cloud API) — opcional</h2>
+        <div class="row">
+          <div><label>Phone Number ID</label><input id="wa-phone" placeholder="ID del número (Meta)" /></div>
+          <div><label>Access Token</label><input id="wa-token" type="password" placeholder="(se guarda cifrado)" /></div>
+        </div>
+        <button style="margin-top:8px;" onclick="saveWhatsapp()">Guardar WhatsApp</button>
+        <p class="muted" id="wa-state"></p>
         <h2 style="margin-top:14px;">Acciones que puede hacer el bot (opt-in)</h2>
         <p class="muted">El bot solo ejecuta estas acciones tras verificar la identidad del cliente. Actívalas bajo tu responsabilidad.</p>
         <label><input type="checkbox" id="act-cancel" style="width:auto;" /> Cancelar pedidos</label>
@@ -166,6 +173,8 @@
       $("assistant").value = t.assistant_name || ""; $("avatar").value = t.avatar_url || ""; $("welcome").value = t.welcome || "";
       $("sh-shop").value = t.shopify_shop || ""; $("sh-id").value = t.shopify_client_id || "";
       $("sh-state").textContent = t.has_shopify_secret ? "Secret guardado ✓" : "Sin secret (bot solo-info)";
+      $("wa-phone").value = t.whatsapp_phone_id || "";
+      $("wa-state").textContent = t.has_whatsapp_token ? "Token guardado ✓" : (t.whatsapp_phone_id ? "Sin token propio (usa el global)" : "Sin WhatsApp conectado");
       $("act-cancel").checked = !!t.allow_cancel; $("act-addr").checked = !!t.allow_address_change; $("act-ret").checked = !!t.allow_returns;
       loadSources(); loadStats();
     }
@@ -236,6 +245,13 @@
       await api("/tenants/" + slug(), { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
       $("sh-secret").value = ""; flash("Shopify guardado."); onTenant();
     }
+    async function saveWhatsapp() {
+      var body = { whatsapp_phone_id: $("wa-phone").value.trim() };
+      var tok = $("wa-token").value.trim(); if (tok) body.whatsapp_token = tok;
+      await api("/tenants/" + slug(), { method: "PUT", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body) });
+      $("wa-token").value = ""; flash("WhatsApp guardado."); onTenant();
+    }
     $("token").addEventListener("change", loadTenants);
   </script>
 </body>

app/config.py

@@ -65,6 +65,16 @@ class Settings(BaseSettings):
     order_verify_lockout_seconds: int = 900
     session_retention_days: int = 30
 
+    # WhatsApp (Meta Cloud API). verify_token: any string you also paste in the
+    # Meta webhook config. app_secret: the Meta app's secret, used to verify
+    # X-Hub-Signature-256 on incoming webhooks (enforced when set).
+    # access_token: global fallback for sending (a per-tenant token wins).
+    whatsapp_verify_token: str = ""
+    whatsapp_app_secret: str = ""
+    whatsapp_access_token: str = ""
+    whatsapp_api_version: str = "v21.0"
+    whatsapp_graph_base: str = "https://graph.facebook.com"
+
     # Escalation (SMTP)
     support_email: str = ""
     smtp_host: str = ""

app/main.py

@@ -10,7 +10,7 @@ from fastapi.middleware.cors import CORSMiddleware
 
 from app import db as dbmod
 from app.config import get_settings
-from app.routes import admin, chat, health, widget
+from app.routes import admin, chat, health, whatsapp, widget
 
 log = logging.getLogger(__name__)
 
@@ -66,6 +66,7 @@ def create_app() -> FastAPI:
     app.include_router(widget.router)
     app.include_router(chat.router)
     app.include_router(admin.router)
+    app.include_router(whatsapp.router)
     return app
 
 

app/models.py

@@ -82,6 +82,11 @@ class Tenant(Base):
     allow_cancel: Mapped[bool] = mapped_column(default=False)
     allow_address_change: Mapped[bool] = mapped_column(default=False)
     allow_returns: Mapped[bool] = mapped_column(default=False)
+    # WhatsApp channel (Meta Cloud API): the business phone_number_id that maps
+    # incoming webhooks to this tenant, plus an optional per-tenant access token
+    # (encrypted; falls back to the global WHATSAPP_ACCESS_TOKEN setting).
+    whatsapp_phone_id: Mapped[str] = mapped_column(String(40), default="", index=True)
+    whatsapp_token_enc: Mapped[str] = mapped_column(Text, default="")
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
 
 

app/routes/admin.py

@@ -59,9 +59,15 @@ async def get_tenants(db: AsyncSession = Depends(get_session)) -> list[TenantOut
 async def post_tenant(body: TenantIn, db: AsyncSession = Depends(get_session)) -> TenantOut:
     if await get_tenant_by_slug(db, body.slug) is not None:
         raise HTTPException(status_code=409, detail="slug already exists")
-    fields = body.model_dump(exclude={"slug", "shopify_client_secret"}, exclude_none=True)
+    fields = body.model_dump(
+        exclude={"slug", "shopify_client_secret", "whatsapp_token"}, exclude_none=True
+    )
     tenant = await create_tenant(
-        db, body.slug, shopify_client_secret=body.shopify_client_secret, **fields
+        db,
+        body.slug,
+        shopify_client_secret=body.shopify_client_secret,
+        whatsapp_token=body.whatsapp_token,
+        **fields,
     )
     await db.commit()
     return TenantOut.from_tenant(tenant)
@@ -72,9 +78,15 @@ async def put_tenant(
     slug: str, body: TenantUpdate, db: AsyncSession = Depends(get_session)
 ) -> TenantOut:
     tenant = await _require_tenant(db, slug)
-    fields = body.model_dump(exclude={"shopify_client_secret"}, exclude_none=True)
+    fields = body.model_dump(
+        exclude={"shopify_client_secret", "whatsapp_token"}, exclude_none=True
+    )
     await update_tenant(
-        db, tenant, shopify_client_secret=body.shopify_client_secret, **fields
+        db,
+        tenant,
+        shopify_client_secret=body.shopify_client_secret,
+        whatsapp_token=body.whatsapp_token,
+        **fields,
     )
     await db.commit()
     return TenantOut.from_tenant(tenant)

app/routes/whatsapp.py

@@ -0,0 +1,146 @@
+"""WhatsApp channel (Meta Cloud API webhook).
+
+A second front door to the SAME conversation brain used by the web widget:
+incoming customer texts run through run_turn() with full per-tenant isolation.
+Tenant resolution: the business phone_number_id on the webhook → Tenant row.
+
+- GET  /whatsapp/webhook — Meta's one-time verification handshake.
+- POST /whatsapp/webhook — incoming messages; signature-checked when the app
+  secret is configured; always answers 200 so Meta doesn't retry-storm
+  (real retries are deduped by message id).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import PlainTextResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app import wa
+from app.config import Settings, get_settings
+from app.db import get_session
+from app.deps import get_router
+from app.models import ChatSession, Tenant
+from app.orchestrator import run_turn
+from app.tenancy import tenant_shopify_client, tenant_whatsapp_token
+from app.tools.registry import ToolContext
+
+log = logging.getLogger(__name__)
+
+router = APIRouter()
+
+_deduper = wa.Deduper()
+_sender: wa.WhatsAppSender | None = None
+
+
+def get_wa_sender(settings: Settings = Depends(get_settings)) -> wa.WhatsAppSender:
+    global _sender
+    if _sender is None:
+        _sender = wa.WhatsAppSender(
+            graph_base=settings.whatsapp_graph_base,
+            api_version=settings.whatsapp_api_version,
+        )
+    return _sender
+
+
+@router.get("/whatsapp/webhook")
+async def verify_webhook(
+    request: Request, settings: Settings = Depends(get_settings)
+) -> PlainTextResponse:
+    params = request.query_params
+    if (
+        params.get("hub.mode") == "subscribe"
+        and settings.whatsapp_verify_token
+        and params.get("hub.verify_token") == settings.whatsapp_verify_token
+    ):
+        return PlainTextResponse(params.get("hub.challenge") or "")
+    raise HTTPException(status_code=403, detail="verification failed")
+
+
+@router.post("/whatsapp/webhook")
+async def receive_webhook(
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    router_=Depends(get_router),
+    settings: Settings = Depends(get_settings),
+    sender: wa.WhatsAppSender = Depends(get_wa_sender),
+) -> dict[str, str]:
+    raw = await request.body()
+    if settings.whatsapp_app_secret and not wa.verify_signature(
+        settings.whatsapp_app_secret, raw, request.headers.get("X-Hub-Signature-256")
+    ):
+        raise HTTPException(status_code=403, detail="bad signature")
+
+    try:
+        payload = json.loads(raw or b"{}")
+    except ValueError:
+        return {"status": "ignored"}
+
+    for msg in wa.parse_incoming(payload):
+        if _deduper.seen(msg.wamid):
+            continue
+        try:
+            await _handle_message(db, router_, settings, sender, msg)
+        except Exception:  # noqa: BLE001 - one bad message must not 500 the batch
+            log.exception("whatsapp message handling failed (wamid=%s)", msg.wamid)
+    return {"status": "ok"}
+
+
+async def _handle_message(
+    db: AsyncSession,
+    router_,
+    settings: Settings,
+    sender: wa.WhatsAppSender,
+    msg: wa.IncomingMessage,
+) -> None:
+    tenant = (
+        await db.execute(
+            select(Tenant).where(Tenant.whatsapp_phone_id == msg.phone_number_id)
+        )
+    ).scalar_one_or_none()
+    if tenant is None:
+        log.warning("whatsapp message for unknown phone_number_id=%s", msg.phone_number_id)
+        return
+
+    # One stable conversation per (tenant, customer phone). We create the row
+    # with our deterministic id ourselves: get_or_create_session would mint a
+    # random id on first contact (and letting clients pick ids is web-unsafe,
+    # so we don't change its semantics).
+    sid = wa.session_id_for(tenant.id, msg.from_phone)
+    session = await db.get(ChatSession, sid)
+    if session is None or session.tenant_id != tenant.id:
+        session = ChatSession(id=sid, shop=tenant.shopify_shop, tenant_id=tenant.id)
+        db.add(session)
+        await db.flush()
+    else:
+        session.last_seen = datetime.now(UTC)
+    ctx = ToolContext(
+        db=db,
+        session=session,
+        shopify=tenant_shopify_client(tenant),
+        tenant_id=tenant.id,
+        shop=tenant.shopify_shop,
+        allow_cancel=tenant.allow_cancel,
+        allow_address_change=tenant.allow_address_change,
+        allow_returns=tenant.allow_returns,
+        support_email=settings.support_email,
+        now=datetime.now(UTC),
+    )
+    response = await run_turn(router_, ctx, msg.text, brand_name=tenant.brand_name)
+    await db.commit()
+
+    body = wa.to_whatsapp_text(response.reply)
+    if response.products:
+        digest = wa.cards_to_text(response.products)
+        if digest:
+            body = f"{body}\n\n{digest}"
+    token = tenant_whatsapp_token(tenant) or settings.whatsapp_access_token
+    if not token:
+        log.error("no whatsapp access token for tenant %s; reply dropped", tenant.slug)
+        return
+    await sender.send_text(msg.phone_number_id, msg.from_phone, body, token=token)

app/schemas.py

@@ -58,6 +58,8 @@ class TenantIn(BaseModel):
     allow_cancel: bool | None = None
     allow_address_change: bool | None = None
     allow_returns: bool | None = None
+    whatsapp_phone_id: str | None = None
+    whatsapp_token: str | None = None
 
 
 class TenantUpdate(BaseModel):
@@ -75,6 +77,8 @@ class TenantUpdate(BaseModel):
     allow_cancel: bool | None = None
     allow_address_change: bool | None = None
     allow_returns: bool | None = None
+    whatsapp_phone_id: str | None = None
+    whatsapp_token: str | None = None
 
 
 class TenantOut(BaseModel):
@@ -94,6 +98,8 @@ class TenantOut(BaseModel):
     allow_cancel: bool
     allow_address_change: bool
     allow_returns: bool
+    whatsapp_phone_id: str
+    has_whatsapp_token: bool
 
     @classmethod
     def from_tenant(cls, t) -> TenantOut:
@@ -114,4 +120,6 @@ class TenantOut(BaseModel):
             allow_cancel=t.allow_cancel,
             allow_address_change=t.allow_address_change,
             allow_returns=t.allow_returns,
+            whatsapp_phone_id=t.whatsapp_phone_id,
+            has_whatsapp_token=bool(t.whatsapp_token_enc),
         )

app/tenancy.py

@@ -54,16 +54,24 @@ _TENANT_FIELDS = {
     "assistant_name",
     "avatar_url",
     "name",
+    "whatsapp_phone_id",
 }
 
 
 async def create_tenant(
-    db: AsyncSession, slug: str, *, shopify_client_secret: str | None = None, **fields: Any
+    db: AsyncSession,
+    slug: str,
+    *,
+    shopify_client_secret: str | None = None,
+    whatsapp_token: str | None = None,
+    **fields: Any,
 ) -> Tenant:
     data = {k: v for k, v in fields.items() if k in _TENANT_FIELDS and v is not None}
     tenant = Tenant(slug=slug, **data)
     if shopify_client_secret:
         tenant.shopify_client_secret_enc = encrypt(shopify_client_secret)
+    if whatsapp_token:
+        tenant.whatsapp_token_enc = encrypt(whatsapp_token)
     db.add(tenant)
     await db.flush()
     _registry.invalidate(tenant.id)
@@ -71,7 +79,12 @@ async def create_tenant(
 
 
 async def update_tenant(
-    db: AsyncSession, tenant: Tenant, *, shopify_client_secret: str | None = None, **fields: Any
+    db: AsyncSession,
+    tenant: Tenant,
+    *,
+    shopify_client_secret: str | None = None,
+    whatsapp_token: str | None = None,
+    **fields: Any,
 ) -> Tenant:
     for k, v in fields.items():
         if k in _TENANT_FIELDS and v is not None:
@@ -80,11 +93,18 @@ async def update_tenant(
         tenant.shopify_client_secret_enc = (
             encrypt(shopify_client_secret) if shopify_client_secret else ""
         )
+    if whatsapp_token is not None:
+        tenant.whatsapp_token_enc = encrypt(whatsapp_token) if whatsapp_token else ""
     await db.flush()
     _registry.invalidate(tenant.id)
     return tenant
 
 
+def tenant_whatsapp_token(tenant: Tenant) -> str:
+    """The tenant's decrypted WhatsApp access token, or "" if not set."""
+    return decrypt(tenant.whatsapp_token_enc) if tenant.whatsapp_token_enc else ""
+
+
 class _ShopifyRegistry:
     """Caches one ShopifyGraphQLClient per tenant (keyed by creds fingerprint)."""
 

app/wa.py

@@ -0,0 +1,154 @@
+"""WhatsApp (Meta Cloud API) channel helpers.
+
+This module is the only WhatsApp-specific code: webhook signature check,
+payload parsing, reply formatting, deterministic per-phone sessions, webhook
+retry dedupe, and the Graph API sender. The conversation brain (orchestrator,
+tools, prompts) is reused untouched.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import re
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+# ── webhook signature ────────────────────────────────────────────────────
+
+def verify_signature(app_secret: str, raw_body: bytes, header: str | None) -> bool:
+    """Validate Meta's X-Hub-Signature-256 header (sha256=<hmac hex>)."""
+    if not header or not header.startswith("sha256="):
+        return False
+    expected = hmac.new(app_secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(header[len("sha256="):], expected)
+
+
+# ── incoming payload parsing ─────────────────────────────────────────────
+
+@dataclass
+class IncomingMessage:
+    phone_number_id: str  # the BUSINESS number that received it (→ tenant)
+    wamid: str  # unique message id (dedupe key for Meta retries)
+    from_phone: str  # customer's phone in international format
+    text: str
+
+
+def parse_incoming(payload: dict[str, Any]) -> list[IncomingMessage]:
+    """Extract text messages from a webhook payload; ignore statuses/media."""
+    out: list[IncomingMessage] = []
+    for entry in payload.get("entry") or []:
+        for change in entry.get("changes") or []:
+            value = change.get("value") or {}
+            phone_number_id = (value.get("metadata") or {}).get("phone_number_id") or ""
+            for msg in value.get("messages") or []:
+                if msg.get("type") != "text":
+                    continue  # v1: text only (media/audio out of scope)
+                body = ((msg.get("text") or {}).get("body") or "").strip()
+                if not (phone_number_id and msg.get("id") and msg.get("from") and body):
+                    continue
+                out.append(
+                    IncomingMessage(
+                        phone_number_id=phone_number_id,
+                        wamid=msg["id"],
+                        from_phone=msg["from"],
+                        text=body,
+                    )
+                )
+    return out
+
+
+# ── sessions: one stable conversation per (tenant, customer phone) ──────
+
+def session_id_for(tenant_id: int, phone: str) -> str:
+    """Deterministic ChatSession id (≤40 chars) so a customer's WhatsApp chat
+    keeps its history and order verification across messages."""
+    digest = hashlib.md5(f"wa:{tenant_id}:{phone}".encode()).hexdigest()
+    return f"wa{digest}"  # 34 chars, fits String(40)
+
+
+# ── webhook retry dedupe ─────────────────────────────────────────────────
+
+class Deduper:
+    """Remember recently-seen message ids (Meta retries webhooks on timeout)."""
+
+    def __init__(self, maxlen: int = 2048) -> None:
+        self._seen: OrderedDict[str, None] = OrderedDict()
+        self._maxlen = maxlen
+
+    def seen(self, key: str) -> bool:
+        """True if key was already seen; otherwise records it and returns False."""
+        if key in self._seen:
+            return True
+        self._seen[key] = None
+        if len(self._seen) > self._maxlen:
+            self._seen.popitem(last=False)
+        return False
+
+
+# ── reply formatting: chat-markdown → WhatsApp ───────────────────────────
+
+_BOLD = re.compile(r"\*\*(.+?)\*\*", re.DOTALL)
+_MD_LINK = re.compile(r"\[([^\]]+)\]\((https?://[^)\s]+)\)")
+_HEADING = re.compile(r"^#{1,6}\s*", re.MULTILINE)
+
+
+def to_whatsapp_text(text: str) -> str:
+    """WhatsApp uses *bold* (single asterisks) and plain URLs, no md links."""
+    text = _BOLD.sub(r"*\1*", text)
+    text = _MD_LINK.sub(r"\1: \2", text)
+    text = _HEADING.sub("", text)
+    return text.strip()
+
+
+def cards_to_text(cards: list[dict[str, Any]], limit: int = 3) -> str:
+    """Compact product-card digest to append after the reply (links work in WA)."""
+    lines: list[str] = []
+    for card in cards[:limit]:
+        title = card.get("title") or "Producto"
+        price = card.get("price") or ""
+        line = f"• *{title}*" + (f" — {price}" if price else "")
+        if card.get("add_url"):
+            line += f"\n  Añadir al carrito: {card['add_url']}"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+# ── outbound sender (Graph API) ──────────────────────────────────────────
+
+class WhatsAppSender:
+    """Thin Graph API client; one instance app-wide (tests inject a fake)."""
+
+    def __init__(self, *, graph_base: str, api_version: str) -> None:
+        self._base = graph_base.rstrip("/")
+        self._version = api_version
+
+    async def send_text(
+        self, phone_number_id: str, to: str, body: str, *, token: str
+    ) -> bool:
+        url = f"{self._base}/{self._version}/{phone_number_id}/messages"
+        payload = {
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "text",
+            "text": {"body": body[:4096], "preview_url": True},
+        }
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                resp = await client.post(
+                    url, json=payload, headers={"Authorization": f"Bearer {token}"}
+                )
+            if resp.status_code >= 400:
+                log.error("whatsapp send failed %s: %s", resp.status_code, resp.text[:300])
+                return False
+            return True
+        except httpx.HTTPError:
+            log.exception("whatsapp send error")
+            return False

migrations/versions/0005_whatsapp.py

@@ -0,0 +1,39 @@
+"""WhatsApp channel: tenant phone_number_id + encrypted access token
+
+Revision ID: 0005_whatsapp
+Revises: 0004_order_actions
+Create Date: 2026-06-10
+
+Additive, idempotent on Postgres. No-op elsewhere (tests use create_all).
+"""
+
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0005_whatsapp"
+down_revision = "0004_order_actions"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute(
+        "ALTER TABLE tenants ADD COLUMN IF NOT EXISTS whatsapp_phone_id VARCHAR(40) NOT NULL DEFAULT ''"
+    )
+    op.execute(
+        "ALTER TABLE tenants ADD COLUMN IF NOT EXISTS whatsapp_token_enc TEXT NOT NULL DEFAULT ''"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_tenants_whatsapp_phone_id ON tenants (whatsapp_phone_id)"
+    )
+
+
+def downgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute("DROP INDEX IF EXISTS ix_tenants_whatsapp_phone_id")
+    op.execute("ALTER TABLE tenants DROP COLUMN IF EXISTS whatsapp_token_enc")
+    op.execute("ALTER TABLE tenants DROP COLUMN IF EXISTS whatsapp_phone_id")

tests/routes/test_whatsapp.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+
+import pytest
+from sqlalchemy import func, select
+
+from app.config import get_settings
+from app.deps import get_router
+from app.llm.base import ChatResult
+from app.models import ChatMessage, ChatSession, Tenant
+from app.routes import whatsapp as wa_route
+
+
+class FakeRouter:
+    def __init__(self, reply="¡Hola! Soy **el bot**."):
+        self.reply = reply
+
+    async def chat(self, messages, tools, tier="large", temperature=None):
+        return ChatResult(content=self.reply, tool_calls=[], finish_reason="stop")
+
+
+class FakeSender:
+    def __init__(self):
+        self.sent: list[dict] = []
+
+    async def send_text(self, phone_number_id, to, body, *, token):
+        self.sent.append(
+            {"phone_number_id": phone_number_id, "to": to, "body": body, "token": token}
+        )
+        return True
+
+
+def _payload(phone_number_id="111", wamid="wamid.A", frm="34600111222", text="hola"):
+    return {
+        "entry": [
+            {"changes": [{"value": {
+                "metadata": {"phone_number_id": phone_number_id},
+                "messages": [{"id": wamid, "from": frm, "type": "text",
+                              "text": {"body": text}}],
+            }}]}
+        ]
+    }
+
+
+@pytest.fixture(autouse=True)
+def fresh_deduper():
+    wa_route._deduper = wa_route.wa.Deduper()
+    yield
+
+
+@pytest.fixture
+def wa_app(app_client, monkeypatch):
+    app, client = app_client
+    app.dependency_overrides[get_router] = lambda: FakeRouter()
+    sender = FakeSender()
+    app.dependency_overrides[wa_route.get_wa_sender] = lambda: sender
+    settings = get_settings()
+    monkeypatch.setattr(settings, "whatsapp_verify_token", "verif-123")
+    monkeypatch.setattr(settings, "whatsapp_app_secret", "")
+    monkeypatch.setattr(settings, "whatsapp_access_token", "global-token")
+    return app, client, sender
+
+
+async def _make_wa_tenant(db, slug="watienda", phone_id="111"):
+    t = Tenant(slug=slug, brand_name="Mi Tienda", whatsapp_phone_id=phone_id)
+    db.add(t)
+    await db.flush()
+    return t
+
+
+async def test_handshake_returns_challenge(wa_app):
+    _app, client, _ = wa_app
+    r = await client.get(
+        "/whatsapp/webhook",
+        params={"hub.mode": "subscribe", "hub.verify_token": "verif-123",
+                "hub.challenge": "42"},
+    )
+    assert r.status_code == 200
+    assert r.text == "42"
+
+
+async def test_handshake_rejects_bad_token(wa_app):
+    _app, client, _ = wa_app
+    r = await client.get(
+        "/whatsapp/webhook",
+        params={"hub.mode": "subscribe", "hub.verify_token": "nope", "hub.challenge": "42"},
+    )
+    assert r.status_code == 403
+
+
+async def test_message_runs_turn_and_replies(wa_app, db_session):
+    _app, client, sender = wa_app
+    await _make_wa_tenant(db_session)
+
+    r = await client.post("/whatsapp/webhook", json=_payload(text="hola tienda"))
+    assert r.status_code == 200
+    assert len(sender.sent) == 1
+    out = sender.sent[0]
+    assert out["to"] == "34600111222"
+    assert out["phone_number_id"] == "111"
+    assert "*el bot*" in out["body"]  # markdown converted for WhatsApp
+    assert "**" not in out["body"]
+    assert out["token"] == "global-token"  # falls back to the global token
+
+    # The turn was persisted under the tenant (same brain as the widget).
+    n = (await db_session.execute(select(func.count(ChatMessage.id)))).scalar_one()
+    assert n == 2  # user + assistant
+
+
+async def test_same_phone_reuses_session(wa_app, db_session):
+    _app, client, _sender = wa_app
+    await _make_wa_tenant(db_session)
+
+    await client.post("/whatsapp/webhook", json=_payload(wamid="w1", text="hola"))
+    await client.post("/whatsapp/webhook", json=_payload(wamid="w2", text="¿envíos?"))
+
+    sessions = (await db_session.execute(select(ChatSession))).scalars().all()
+    assert len(sessions) == 1  # one stable conversation per phone
+
+
+async def test_duplicate_wamid_processed_once(wa_app, db_session):
+    _app, client, sender = wa_app
+    await _make_wa_tenant(db_session)
+
+    await client.post("/whatsapp/webhook", json=_payload(wamid="dup"))
+    await client.post("/whatsapp/webhook", json=_payload(wamid="dup"))
+    assert len(sender.sent) == 1
+
+
+async def test_unknown_phone_id_ignored(wa_app, db_session):
+    _app, client, sender = wa_app
+    await _make_wa_tenant(db_session, phone_id="999")
+
+    r = await client.post("/whatsapp/webhook", json=_payload(phone_number_id="111"))
+    assert r.status_code == 200  # never 500/404 back to Meta
+    assert sender.sent == []
+
+
+async def test_statuses_only_payload_ignored(wa_app):
+    _app, client, sender = wa_app
+    payload = {"entry": [{"changes": [{"value": {
+        "metadata": {"phone_number_id": "111"},
+        "statuses": [{"id": "wamid.X", "status": "delivered"}],
+    }}]}]}
+    r = await client.post("/whatsapp/webhook", json=payload)
+    assert r.status_code == 200
+    assert sender.sent == []
+
+
+async def test_signature_enforced_when_secret_set(wa_app, db_session, monkeypatch):
+    _app, client, sender = wa_app
+    await _make_wa_tenant(db_session)
+    settings = get_settings()
+    monkeypatch.setattr(settings, "whatsapp_app_secret", "app-secret")
+
+    body = json.dumps(_payload()).encode()
+    bad = await client.post(
+        "/whatsapp/webhook", content=body,
+        headers={"Content-Type": "application/json", "X-Hub-Signature-256": "sha256=bad"},
+    )
+    assert bad.status_code == 403
+    assert sender.sent == []
+
+    good_sig = "sha256=" + hmac.new(b"app-secret", body, hashlib.sha256).hexdigest()
+    ok = await client.post(
+        "/whatsapp/webhook", content=body,
+        headers={"Content-Type": "application/json", "X-Hub-Signature-256": good_sig},
+    )
+    assert ok.status_code == 200
+    assert len(sender.sent) == 1
+
+
+async def test_tenant_isolation_two_stores(wa_app, db_session):
+    _app, client, sender = wa_app
+    a = await _make_wa_tenant(db_session, slug="store-a", phone_id="111")
+    b = await _make_wa_tenant(db_session, slug="store-b", phone_id="222")
+
+    await client.post("/whatsapp/webhook", json=_payload(phone_number_id="111", wamid="m1"))
+    await client.post("/whatsapp/webhook", json=_payload(phone_number_id="222", wamid="m2"))
+
+    sessions = (await db_session.execute(select(ChatSession))).scalars().all()
+    by_tenant = {s.tenant_id for s in sessions}
+    assert by_tenant == {a.id, b.id}  # same customer phone, separate conversations
+    assert len(sender.sent) == 2

tests/test_onboarding_e2e.py

@@ -0,0 +1,103 @@
+"""End-to-end onboarding proof: a brand-new client, REAL extraction + REAL
+embeddings (no index mock), answering only from ITS OWN uploaded document,
+fully isolated from another client. This is the "can I onboard a real store
+and trust it" guarantee.
+
+Marked slow because it loads the embedding model.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from app.models import ChatSession
+from app.tenancy import get_tenant_by_slug
+from app.tools import knowledge_tool
+from app.tools.registry import ToolContext
+
+AUTH = {"Authorization": "Bearer test-admin-token"}
+
+# Distinctive facts with rare tokens so retrieval + isolation are unambiguous.
+CLIENT_A = {
+    "slug": "mochilas-trekmax",
+    "brand": "Mochilas TrekMax",
+    "file": ("garantia.md", b"La garantia de la mochila TrekMax Summit es de siete anos. "
+                            b"El material es Cordura 1000D totalmente impermeable.", "text/markdown"),
+    "ask": "cuanto dura la garantia de la mochila summit y de que material es",
+    "must_have": "TrekMax",
+    "must_not_have": "GotaFina",
+}
+CLIENT_B = {
+    "slug": "riego-gotafina",
+    "brand": "Riego GotaFina",
+    "file": ("kit.md", b"El kit de riego GotaFina incluye 30 metros de manguera de "
+                       b"poliuretano y boquillas de laton macizo.", "text/markdown"),
+    "ask": "que incluye el kit de riego y de que son las boquillas",
+    "must_not_have": "TrekMax",
+    "must_have": "GotaFina",
+}
+
+
+async def _onboard(client, db, c):
+    # 1) Create the tenant with its brand (what the admin form does).
+    created = await client.post(
+        "/admin/tenants", headers=AUTH,
+        json={"slug": c["slug"], "brand_name": c["brand"]},
+    )
+    assert created.status_code == 201, created.text
+    assert created.json()["brand_name"] == c["brand"]
+    assert created.json()["has_shopify_secret"] is False
+
+    # 2) Set its Shopify credentials — secret is stored encrypted, never echoed.
+    upd = await client.put(
+        f"/admin/tenants/{c['slug']}", headers=AUTH,
+        json={"shopify_shop": f"{c['slug']}.myshopify.com",
+              "shopify_client_id": "id123",
+              "shopify_client_secret": "shpss_super_secret"},
+    )
+    assert upd.status_code == 200
+    assert upd.json()["has_shopify_secret"] is True
+
+    # 3) Upload its real document — REAL extract -> chunk -> embed -> store.
+    up = await client.post(
+        f"/admin/tenants/{c['slug']}/sources/file", headers=AUTH,
+        files={"file": c["file"]},
+    )
+    assert up.status_code == 201, up.text
+    assert up.json()["status"] == "indexed", up.json()
+    assert up.json().get("error") in (None, "")
+
+    tenant = await get_tenant_by_slug(db, c["slug"])
+    return tenant.id
+
+
+@pytest.mark.slow
+async def test_full_client_onboarding_and_isolation(app_client, db_session):
+    _app, client = app_client
+    try:
+        a_id = await _onboard(client, db_session, CLIENT_A)
+        b_id = await _onboard(client, db_session, CLIENT_B)
+
+        async def ask(tenant_id, question):
+            ctx = ToolContext(
+                db=db_session,
+                session=ChatSession(shop="x", tenant_id=tenant_id),
+                tenant_id=tenant_id,
+            )
+            return (await knowledge_tool.run({"query": question}, ctx))["context"]
+
+        # Client A's bot answers from A's doc, and NEVER sees B's.
+        a_ctx = await ask(a_id, CLIENT_A["ask"])
+        assert CLIENT_A["must_have"] in a_ctx, a_ctx
+        assert CLIENT_A["must_not_have"] not in a_ctx, f"LEAK from other tenant: {a_ctx}"
+
+        # Client B's bot answers from B's doc, and NEVER sees A's.
+        b_ctx = await ask(b_id, CLIENT_B["ask"])
+        assert CLIENT_B["must_have"] in b_ctx, b_ctx
+        assert CLIENT_B["must_not_have"] not in b_ctx, f"LEAK from other tenant: {b_ctx}"
+    finally:
+        shutil.rmtree(Path("uploads") / CLIENT_A["slug"], ignore_errors=True)
+        shutil.rmtree(Path("uploads") / CLIENT_B["slug"], ignore_errors=True)

tests/test_wa_format.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from app.wa import (
+    Deduper,
+    cards_to_text,
+    parse_incoming,
+    session_id_for,
+    to_whatsapp_text,
+    verify_signature,
+)
+
+
+def _sig(secret: str, body: bytes) -> str:
+    return "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+
+def test_verify_signature_roundtrip():
+    body = b'{"hola": 1}'
+    assert verify_signature("s3cret", body, _sig("s3cret", body)) is True
+    assert verify_signature("s3cret", body, _sig("wrong", body)) is False
+    assert verify_signature("s3cret", body, None) is False
+    assert verify_signature("s3cret", body, "md5=abc") is False
+
+
+def test_to_whatsapp_text_converts_markdown():
+    md = "**Manguera plana** de PVC\n\n- [Ver carrito](https://x.com/cart/1:1)\n## Detalles"
+    out = to_whatsapp_text(md)
+    assert "*Manguera plana*" in out
+    assert "**" not in out
+    assert "Ver carrito: https://x.com/cart/1:1" in out
+    assert "##" not in out
+
+
+def test_cards_to_text_caps_and_links():
+    cards = [
+        {"title": f"Prod {i}", "price": "9,99 €", "add_url": f"https://s/cart/{i}:1"}
+        for i in range(5)
+    ]
+    out = cards_to_text(cards)
+    assert out.count("•") == 3  # capped
+    assert "*Prod 0*" in out and "https://s/cart/0:1" in out
+
+
+def test_session_id_deterministic_and_fits_column():
+    a = session_id_for(1, "34600111222")
+    assert a == session_id_for(1, "34600111222")  # stable per phone
+    assert a != session_id_for(2, "34600111222")  # tenant-scoped
+    assert a != session_id_for(1, "34600999888")  # phone-scoped
+    assert len(a) <= 40 and a.startswith("wa")
+
+
+def test_deduper_remembers_and_evicts():
+    d = Deduper(maxlen=2)
+    assert d.seen("a") is False
+    assert d.seen("a") is True
+    d.seen("b"), d.seen("c")  # evicts "a"
+    assert d.seen("a") is False
+
+
+def test_parse_incoming_extracts_text_and_skips_statuses():
+    payload = {
+        "entry": [
+            {
+                "changes": [
+                    {
+                        "value": {
+                            "metadata": {"phone_number_id": "111"},
+                            "messages": [
+                                {"id": "wamid.1", "from": "34600111222", "type": "text",
+                                 "text": {"body": "hola"}},
+                                {"id": "wamid.2", "from": "34600111222", "type": "image"},
+                            ],
+                        }
+                    },
+                    {"value": {"metadata": {"phone_number_id": "111"},
+                               "statuses": [{"id": "wamid.1", "status": "delivered"}]}},
+                ]
+            }
+        ]
+    }
+    msgs = parse_incoming(payload)
+    assert len(msgs) == 1
+    assert msgs[0].wamid == "wamid.1"
+    assert msgs[0].phone_number_id == "111"
+    assert msgs[0].from_phone == "34600111222"
+    assert msgs[0].text == "hola"