whatsapp: align API version + register number on Cloud API after embedded-signup connect

app/routes/admin.py

@@ -260,6 +260,9 @@ async def connect_whatsapp(
         "status": "connected",
         "display_phone_number": result["display_phone_number"],
         "verified_name": result["verified_name"],
+        # "true" once the number is registered on Cloud API (can SEND replies);
+        # "false" = receive-only, registration needs attention (e.g. a 2FA PIN).
+        "registered": "true" if result.get("registered") else "false",
     }
 
 
@@ -316,6 +319,9 @@ async def whatsapp_embedded_signup(
         "status": "connected",
         "display_phone_number": result["display_phone_number"],
         "verified_name": result["verified_name"],
+        # "true" once the number is registered on Cloud API (can SEND replies);
+        # "false" = receive-only, registration needs attention (e.g. a 2FA PIN).
+        "registered": "true" if result.get("registered") else "false",
     }
 
 

app/wa.py

@@ -13,6 +13,7 @@ import hashlib
 import hmac
 import logging
 import re
+import secrets
 from collections import OrderedDict
 from dataclasses import dataclass
 from typing import Any
@@ -229,7 +230,7 @@ async def exchange_code(
     app_id: str,
     app_secret: str,
     graph_base: str = "https://graph.facebook.com",
-    api_version: str = "v25.0",
+    api_version: str = "v21.0",
 ) -> dict[str, Any]:
     """Exchange an Embedded Signup auth code for the client's business token.
 
@@ -255,19 +256,53 @@ async def exchange_code(
     return {"ok": True, "token": token}
 
 
+def _gen_pin() -> str:
+    """A random 6-digit Cloud API two-step PIN for number registration."""
+    return f"{secrets.randbelow(900000) + 100000}"
+
+
+async def _register_number(
+    client: httpx.AsyncClient, *, base: str, api_version: str,
+    phone_number_id: str, headers: dict[str, str], pin: str,
+) -> dict[str, Any]:
+    """Register the number on Cloud API. Embedded Signup subscribes the WABA but
+    does NOT register the phone — without this, SENDING replies can fail (errors
+    133010 'already registered' / 131045 'not registered'). Idempotent: an
+    already-registered number counts as success."""
+    try:
+        resp = await client.post(
+            f"{base}/{api_version}/{phone_number_id}/register",
+            headers={**headers, "Content-Type": "application/json"},
+            json={"messaging_product": "whatsapp", "pin": pin},
+        )
+    except httpx.HTTPError as exc:
+        return {"registered": False, "error": f"network: {exc}"}
+    if resp.status_code < 400:
+        return {"registered": True}
+    body = resp.text
+    # already registered -> idempotent success (133010, or the textual hint)
+    if "133010" in body or "already" in body.lower():
+        return {"registered": True, "note": "already_registered"}
+    return {"registered": False, "error": f"register_failed: {body[:300]}"}
+
+
 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",
+    api_version: str = "v21.0",
+    register_pin: str = "",
 ) -> dict[str, Any]:
-    """Subscribe a client's WABA to our app and validate the phone number.
+    """Subscribe a client's WABA to our app, validate the phone, and REGISTER it
+    on Cloud API (so the number can both receive AND send).
 
     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": ...}.
+    Returns {"ok": True, "display_phone_number": ..., "registered": bool} or
+    {"ok": False, "error": ...}. ``registered`` is surfaced (not fatal) so the
+    flow can still save a receive-only connection and flag send-readiness.
     """
     base = graph_base.rstrip("/")
     headers = {"Authorization": f"Bearer {token}"}
@@ -286,10 +321,19 @@ async def connect_number(
             if info.status_code >= 400:
                 return {"ok": False, "error": f"phone_check_failed: {info.text[:300]}"}
             data = info.json()
+            reg = await _register_number(
+                client, base=base, api_version=api_version,
+                phone_number_id=phone_number_id, headers=headers,
+                pin=register_pin or _gen_pin(),
+            )
     except httpx.HTTPError as exc:
         return {"ok": False, "error": f"network: {exc}"}
-    return {
+    out = {
         "ok": True,
         "display_phone_number": data.get("display_phone_number", ""),
         "verified_name": data.get("verified_name", ""),
+        "registered": reg["registered"],
     }
+    if not reg["registered"]:
+        out["register_error"] = reg.get("error", "")
+    return out