feat: one-click whatsapp onboarding

GUIA_WHATSAPP.md

@@ -66,6 +66,33 @@ teléfono y firma de seguridad. Solo falta el papeleo de Meta (esta guía).
 - 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

app/admin_ui/index.html

@@ -114,11 +114,15 @@
         </div>
         <p class="muted" id="sh-state"></p>
         <h2 style="margin-top:14px;">WhatsApp (Meta Cloud API) — opcional</h2>
+        <p class="muted">Alta en 1 clic: suscribe el WABA del cliente a la app, valida el número y lo conecta a esta tienda. El webhook ya es global (no hay que tocarlo).</p>
         <div class="row">
+          <div><label>WABA ID</label><input id="wa-waba" placeholder="WhatsApp Business Account ID" /></div>
           <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>
+        <div class="row" style="margin-top:8px;">
+          <div><label>Access Token</label><input id="wa-token" type="password" placeholder="(se guarda cifrado; vacío = usar el ya guardado/global)" /></div>
+          <button onclick="connectWhatsapp()">Conectar número</button>
+        </div>
         <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>
@@ -245,12 +249,20 @@
       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" },
+    async function connectWhatsapp() {
+      var body = { waba_id: $("wa-waba").value.trim(), phone_number_id: $("wa-phone").value.trim() };
+      var tok = $("wa-token").value.trim(); if (tok) body.token = tok;
+      var r = await api("/tenants/" + slug() + "/whatsapp/connect", {
+        method: "POST", headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body) });
-      $("wa-token").value = ""; flash("WhatsApp guardado."); onTenant();
+      if (r.ok) {
+        var d = await r.json();
+        flash("WhatsApp conectado: " + (d.display_phone_number || "OK"));
+      } else {
+        var e = await r.json().catch(function () { return {}; });
+        flash("Error al conectar: " + (e.detail || r.status));
+      }
+      $("wa-token").value = ""; onTenant();
     }
     $("token").addEventListener("change", loadTenants);
   </script>

app/routes/admin.py

@@ -14,12 +14,20 @@ from fastapi.responses import HTMLResponse
 from sqlalchemy import delete, 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 require_admin
 from app.models import ChatMessage, ChatSession, KnowledgeChunk, KnowledgeSource, Tenant
 from app.rag import index
-from app.schemas import SourceIn, SourceOut, TenantIn, TenantOut, TenantUpdate
-from app.tenancy import create_tenant, get_tenant_by_slug, list_tenants, update_tenant
+from app.schemas import SourceIn, SourceOut, TenantIn, TenantOut, TenantUpdate, WhatsAppConnectIn
+from app.tenancy import (
+    create_tenant,
+    get_tenant_by_slug,
+    list_tenants,
+    tenant_whatsapp_token,
+    update_tenant,
+)
 
 router = APIRouter(prefix="/admin")
 
@@ -92,6 +100,47 @@ async def put_tenant(
     return TenantOut.from_tenant(tenant)
 
 
+@router.post("/tenants/{slug}/whatsapp/connect", dependencies=[Depends(require_admin)])
+async def connect_whatsapp(
+    slug: str,
+    body: WhatsAppConnectIn,
+    db: AsyncSession = Depends(get_session),
+    settings: Settings = Depends(get_settings),
+) -> dict[str, str]:
+    """One-click WhatsApp onboarding for a store: subscribe its WABA to our app
+    (the app-level webhook is already global), validate the number, and save
+    everything on the tenant. After this, the number answers automatically."""
+    tenant = await _require_tenant(db, slug)
+    token = (
+        body.token
+        or tenant_whatsapp_token(tenant)
+        or settings.whatsapp_access_token
+    )
+    if not token:
+        raise HTTPException(status_code=422, detail="no access token (body, tenant or global)")
+    result = await wa.connect_number(
+        waba_id=body.waba_id,
+        phone_number_id=body.phone_number_id,
+        token=token,
+        graph_base=settings.whatsapp_graph_base,
+        api_version=settings.whatsapp_api_version,
+    )
+    if not result["ok"]:
+        raise HTTPException(status_code=502, detail=result["error"])
+    await update_tenant(
+        db,
+        tenant,
+        whatsapp_token=body.token,  # only stored when provided (None = keep)
+        whatsapp_phone_id=body.phone_number_id,
+    )
+    await db.commit()
+    return {
+        "status": "connected",
+        "display_phone_number": result["display_phone_number"],
+        "verified_name": result["verified_name"],
+    }
+
+
 @router.delete("/tenants/{slug}", dependencies=[Depends(require_admin)])
 async def delete_tenant(
     slug: str, db: AsyncSession = Depends(get_session)

app/schemas.py

@@ -81,6 +81,12 @@ class TenantUpdate(BaseModel):
     whatsapp_token: str | None = None
 
 
+class WhatsAppConnectIn(BaseModel):
+    waba_id: str = Field(min_length=1)
+    phone_number_id: str = Field(min_length=1)
+    token: str | None = None  # stored encrypted on the tenant when provided
+
+
 class TenantOut(BaseModel):
     id: int
     slug: str

app/wa.py

@@ -152,3 +152,45 @@ class WhatsAppSender:
         except httpx.HTTPError:
             log.exception("whatsapp send error")
             return False
+
+
+# ── one-click client onboarding (Graph API) ──────────────────────────────
+
+async def connect_number(
+    *,
+    waba_id: str,
+    phone_number_id: str,
+    token: str,
+    graph_base: str = "https://graph.facebook.com",
+    api_version: str = "v25.0",
+) -> dict[str, Any]:
+    """Subscribe a client's WABA to our app and validate the phone number.
+
+    The app-level webhook is configured once globally, so after this call the
+    number's incoming messages reach /whatsapp/webhook with no further setup.
+    Returns {"ok": True, "display_phone_number": ...} or {"ok": False, "error": ...}.
+    """
+    base = graph_base.rstrip("/")
+    headers = {"Authorization": f"Bearer {token}"}
+    try:
+        async with httpx.AsyncClient(timeout=20.0) as client:
+            sub = await client.post(
+                f"{base}/{api_version}/{waba_id}/subscribed_apps", headers=headers
+            )
+            if sub.status_code >= 400:
+                return {"ok": False, "error": f"subscribe_failed: {sub.text[:300]}"}
+            info = await client.get(
+                f"{base}/{api_version}/{phone_number_id}",
+                params={"fields": "display_phone_number,verified_name"},
+                headers=headers,
+            )
+            if info.status_code >= 400:
+                return {"ok": False, "error": f"phone_check_failed: {info.text[:300]}"}
+            data = info.json()
+    except httpx.HTTPError as exc:
+        return {"ok": False, "error": f"network: {exc}"}
+    return {
+        "ok": True,
+        "display_phone_number": data.get("display_phone_number", ""),
+        "verified_name": data.get("verified_name", ""),
+    }

tests/routes/test_whatsapp_connect.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import httpx
+import respx
+
+AUTH = {"Authorization": "Bearer test-admin-token"}
+
+GRAPH = "https://graph.facebook.com/v21.0"  # default test settings version
+
+
+async def _tenant(client, slug="cliente1"):
+    r = await client.post("/admin/tenants", headers=AUTH, json={"slug": slug})
+    assert r.status_code == 201
+
+
+@respx.mock
+async def test_connect_subscribes_validates_and_saves(app_client):
+    _app, client = app_client
+    await _tenant(client)
+
+    sub = respx.post(f"{GRAPH}/WABA1/subscribed_apps").mock(
+        return_value=httpx.Response(200, json={"success": True})
+    )
+    respx.get(f"{GRAPH}/PHONE1").mock(
+        return_value=httpx.Response(
+            200, json={"display_phone_number": "+34 600 000 000",
+                       "verified_name": "Cliente 1", "id": "PHONE1"}
+        )
+    )
+
+    r = await client.post(
+        "/admin/tenants/cliente1/whatsapp/connect", headers=AUTH,
+        json={"waba_id": "WABA1", "phone_number_id": "PHONE1", "token": "tok-123"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "connected"
+    assert body["display_phone_number"] == "+34 600 000 000"
+    assert sub.called
+    # Bearer token used on the Graph calls
+    assert sub.calls[0].request.headers["Authorization"] == "Bearer tok-123"
+
+    # Saved on the tenant (phone id visible, token encrypted not echoed)
+    t = [x for x in (await client.get("/admin/tenants", headers=AUTH)).json()
+         if x["slug"] == "cliente1"][0]
+    assert t["whatsapp_phone_id"] == "PHONE1"
+    assert t["has_whatsapp_token"] is True
+
+
+@respx.mock
+async def test_connect_surfaces_graph_error(app_client):
+    _app, client = app_client
+    await _tenant(client, "cliente2")
+    respx.post(f"{GRAPH}/WABA2/subscribed_apps").mock(
+        return_value=httpx.Response(401, json={"error": {"message": "bad token"}})
+    )
+
+    r = await client.post(
+        "/admin/tenants/cliente2/whatsapp/connect", headers=AUTH,
+        json={"waba_id": "WABA2", "phone_number_id": "P", "token": "expired"},
+    )
+    assert r.status_code == 502
+    assert "subscribe_failed" in r.json()["detail"]
+
+    # nothing saved on failure
+    t = [x for x in (await client.get("/admin/tenants", headers=AUTH)).json()
+         if x["slug"] == "cliente2"][0]
+    assert t["whatsapp_phone_id"] == ""
+
+
+async def test_connect_requires_some_token(app_client):
+    _app, client = app_client
+    await _tenant(client, "cliente3")
+    r = await client.post(
+        "/admin/tenants/cliente3/whatsapp/connect", headers=AUTH,
+        json={"waba_id": "W", "phone_number_id": "P"},
+    )
+    assert r.status_code == 422
+
+
+async def test_connect_requires_admin(app_client):
+    _app, client = app_client
+    r = await client.post(
+        "/admin/tenants/x/whatsapp/connect",
+        json={"waba_id": "W", "phone_number_id": "P"},
+    )
+    assert r.status_code == 401