feat: add optional WhatsApp integration with toggle support and status tracking

.env.example

@@ -133,6 +133,10 @@ GATEWAY_TOKEN=your_gateway_token_here
 # OPENCLAW_PASSWORD=your_password_here
 
 # ── OPTIONAL: Chat Integrations ──
+# Enable WhatsApp pairing flow
+# Set to true only if you want WhatsApp enabled
+WHATSAPP_ENABLED=false
+
 # Get bot token from: https://t.me/BotFather
 TELEGRAM_BOT_TOKEN=your_bot_token_here
 

README.md

@@ -98,10 +98,9 @@ After restarting, the bot should appear online on Telegram.
 
 To use WhatsApp:
 
-1. Visit your Space URL. It opens the dashboard at `/dashboard` by default, then click **Open Control UI**.
-2. Enter your `GATEWAY_TOKEN` when the Control UI prompts you to log in.
-3. In the Control UI, go to **Channels** → **WhatsApp** → **Login**.
-4. Scan the QR code with your phone. 📱
+1. Add `WHATSAPP_ENABLED=true` in Hugging Face Space Variables or Secrets.
+2. In the Control UI, go to **Channels** → **WhatsApp** → **Login**.
+3. Scan the QR code with your phone. 📱
 
 ## 💾 Workspace Backup *(Optional)*
 
@@ -139,6 +138,15 @@ See `.env.example` for runtime settings. Key configuration values:
 | `LLM_MODEL`     | Model ID (prefix `<provider>/`, auto-detected from prefix)  |
 | `GATEWAY_TOKEN` | Gateway token for Control UI access (required)              |
 
+### Chat Integrations
+
+| Variable              | Default | Description                                        |
+|-----------------------|---------|----------------------------------------------------|
+| `WHATSAPP_ENABLED`    | `false` | Enable WhatsApp pairing/login support              |
+| `TELEGRAM_BOT_TOKEN`  | —       | Telegram bot token from BotFather                  |
+| `TELEGRAM_USER_ID`    | —       | Single Telegram user ID allowlist                  |
+| `TELEGRAM_USER_IDS`   | —       | Comma-separated Telegram user IDs for team access  |
+
 ### Background Services
 
 | Variable              | Default | Description                                 |

health-server.js

@@ -2,24 +2,15 @@
 const http = require("http");
 const fs = require("fs");
 const net = require("net");
-const { randomUUID } = require("node:crypto");
 
 const PORT = 7861;
 const GATEWAY_PORT = 7860;
 const GATEWAY_HOST = "127.0.0.1";
 const startTime = Date.now();
 const LLM_MODEL = process.env.LLM_MODEL || "Not Set";
-const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "";
 const TELEGRAM_ENABLED = !!process.env.TELEGRAM_BOT_TOKEN;
-const GATEWAY_STATUS_CACHE_MS = 5000;
-
-let gatewayStatusCache = {
-  expiresAt: 0,
-  value: {
-    whatsapp: { configured: true, connected: false },
-    telegram: { configured: TELEGRAM_ENABLED, connected: false },
-  },
-};
+const WHATSAPP_ENABLED = /^true$/i.test(process.env.WHATSAPP_ENABLED || "");
+const WHATSAPP_STATUS_FILE = "/tmp/huggingclaw-wa-status.json";
 
 function parseRequestUrl(url) {
   try {
@@ -74,117 +65,21 @@ function normalizeChannelStatus(channel, configured) {
   };
 }
 
-function extractErrorMessage(msg) {
-  if (!msg || typeof msg !== "object") return "Unknown error";
-  if (typeof msg.error === "string") return msg.error;
-  if (msg.error && typeof msg.error.message === "string") return msg.error.message;
-  if (typeof msg.message === "string") return msg.message;
-  return "Unknown error";
-}
-
-function createGatewayConnection() {
-  return new Promise((resolve, reject) => {
-    const { WebSocket } = require("/home/node/.openclaw/openclaw-app/node_modules/ws");
-    const ws = new WebSocket(`ws://${GATEWAY_HOST}:${GATEWAY_PORT}`);
-    let resolved = false;
-
-    ws.on("message", (data) => {
-      const msg = JSON.parse(data.toString());
-
-      if (msg.type === "event" && msg.event === "connect.challenge") {
-        ws.send(JSON.stringify({
-          type: "req",
-          id: randomUUID(),
-          method: "connect",
-          params: {
-            minProtocol: 3,
-            maxProtocol: 3,
-            client: {
-              id: "health-server",
-              version: "1.0.0",
-              platform: "linux",
-              mode: "backend",
-            },
-            caps: [],
-            auth: { token: GATEWAY_TOKEN },
-            role: "operator",
-            scopes: ["operator.read"],
-          },
-        }));
-        return;
-      }
-
-      if (!resolved && msg.type === "res" && msg.ok === false) {
-        resolved = true;
-        ws.close();
-        reject(new Error(extractErrorMessage(msg)));
-        return;
-      }
-
-      if (!resolved && msg.type === "res" && msg.ok) {
-        resolved = true;
-        resolve(ws);
-      }
-    });
-
-    ws.on("error", (error) => {
-      if (!resolved) reject(error);
-    });
-
-    setTimeout(() => {
-      if (!resolved) {
-        ws.close();
-        reject(new Error("Timeout"));
-      }
-    }, 10000);
-  });
-}
-
-function callGatewayRpc(ws, method, params) {
-  return new Promise((resolve, reject) => {
-    const id = randomUUID();
-    const handler = (data) => {
-      const msg = JSON.parse(data.toString());
-      if (msg.id === id) {
-        ws.removeListener("message", handler);
-        resolve(msg);
-      }
-    };
-
-    ws.on("message", handler);
-    ws.send(JSON.stringify({ type: "req", id, method, params }));
-
-    setTimeout(() => {
-      ws.removeListener("message", handler);
-      reject(new Error("RPC Timeout"));
-    }, 15000);
-  });
-}
-
-async function getGatewayChannelStatus() {
-  if (Date.now() < gatewayStatusCache.expiresAt) {
-    return gatewayStatusCache.value;
+function readGuardianStatus() {
+  if (!WHATSAPP_ENABLED) {
+    return { configured: false, connected: false, pairing: false };
   }
-
-  let ws;
   try {
-    ws = await createGatewayConnection();
-    const statusRes = await callGatewayRpc(ws, "channels.status", {});
-    const channels = (statusRes.payload || statusRes.result)?.channels || {};
-    const value = {
-      whatsapp: normalizeChannelStatus(channels.whatsapp, true),
-      telegram: normalizeChannelStatus(channels.telegram, TELEGRAM_ENABLED),
-    };
-    gatewayStatusCache = {
-      expiresAt: Date.now() + GATEWAY_STATUS_CACHE_MS,
-      value,
-    };
-    return value;
-  } catch {
-    return gatewayStatusCache.value;
-  } finally {
-    if (ws) ws.close();
-  }
+    if (fs.existsSync(WHATSAPP_STATUS_FILE)) {
+      const parsed = JSON.parse(fs.readFileSync(WHATSAPP_STATUS_FILE, "utf8"));
+      return {
+        configured: parsed.configured !== false,
+        connected: parsed.connected === true,
+        pairing: parsed.pairing === true,
+      };
+    }
+  } catch {}
+  return { configured: true, connected: false, pairing: false };
 }
 
 function renderDashboard() {
@@ -570,13 +465,17 @@ const server = http.createServer((req, res) => {
 
   if (pathname === "/status") {
     void (async () => {
-      const channelStatus = await getGatewayChannelStatus();
+      const guardianStatus = readGuardianStatus();
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(
         JSON.stringify({
           model: LLM_MODEL,
-          whatsapp: channelStatus.whatsapp,
-          telegram: channelStatus.telegram,
+          whatsapp: {
+            configured: guardianStatus.configured,
+            connected: guardianStatus.connected,
+            pairing: guardianStatus.pairing,
+          },
+          telegram: normalizeChannelStatus(null, TELEGRAM_ENABLED),
           sync: readSyncStatus(),
           uptime: uptimeHuman,
         }),

start.sh

@@ -7,6 +7,8 @@ set -e
 
 # ── Startup Banner ──
 OPENCLAW_VERSION="${OPENCLAW_VERSION:-latest}"
+WHATSAPP_ENABLED="${WHATSAPP_ENABLED:-false}"
+WHATSAPP_ENABLED_NORMALIZED=$(printf '%s' "$WHATSAPP_ENABLED" | tr '[:upper:]' '[:lower:]')
 echo ""
 echo "  ╔══════════════════════════════════════════╗"
 echo "  ║          🦞 HuggingClaw Gateway          ║"
@@ -166,7 +168,7 @@ fi
 # ── Restore persisted WhatsApp credentials (if present) ──
 WA_BACKUP_DIR="/home/node/.openclaw/workspace/.huggingclaw-state/credentials/whatsapp/default"
 WA_CREDS_DIR="/home/node/.openclaw/credentials/whatsapp/default"
-if [ -d "$WA_BACKUP_DIR" ]; then
+if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ] && [ -d "$WA_BACKUP_DIR" ]; then
   WA_FILE_COUNT=$(find "$WA_BACKUP_DIR" -type f | wc -l | tr -d ' ')
   if [ "$WA_FILE_COUNT" -ge 2 ]; then
     echo "📱 Restoring WhatsApp credentials..."
@@ -252,9 +254,11 @@ if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
   fi
 fi
 
-# WhatsApp
-CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.plugins.entries.whatsapp = {"enabled": true}')
-CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.channels.whatsapp = {"dmPolicy": "pairing"}')
+# WhatsApp (optional)
+if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ]; then
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.plugins.entries.whatsapp = {"enabled": true}')
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.channels.whatsapp = {"dmPolicy": "pairing"}')
+fi
 
 # Write config
 echo "$CONFIG_JSON" > "/home/node/.openclaw/openclaw.json"
@@ -311,7 +315,11 @@ printf "  │  %-40s │\n" "Telegram: ✅ enabled"
 else
 printf "  │  %-40s │\n" "Telegram: ❌ not configured"
 fi
+if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ]; then
 printf "  │  %-40s │\n" "WhatsApp: ✅ enabled"
+else
+printf "  │  %-40s │\n" "WhatsApp: ❌ disabled"
+fi
 if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
 printf "  │  %-40s │\n" "Backup: ✅ ${HF_USERNAME}/${BACKUP_DATASET:-huggingclaw-backup}"
 else
@@ -408,9 +416,11 @@ if ! kill -0 $GATEWAY_PID 2>/dev/null; then
 fi
 
 # 12. Start WhatsApp Guardian after the gateway is accepting connections
-node /home/node/app/wa-guardian.js &
-GUARDIAN_PID=$!
-echo "🛡️ WhatsApp Guardian started (PID: $GUARDIAN_PID)"
+if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ]; then
+  node /home/node/app/wa-guardian.js &
+  GUARDIAN_PID=$!
+  echo "🛡️ WhatsApp Guardian started (PID: $GUARDIAN_PID)"
+fi
 
 # 13. Start Workspace Sync after startup settles
 python3 -u /home/node/app/workspace-sync.py &

wa-guardian.js

@@ -9,13 +9,12 @@
 
 const fs = require("fs");
 const path = require("path");
-const {
-  WebSocket,
-} = require("/home/node/.openclaw/openclaw-app/node_modules/ws");
-const { randomUUID } = require("node:crypto");
+const { WebSocket } = require('/home/node/.openclaw/openclaw-app/node_modules/ws');
+const { randomUUID } = require('node:crypto');
 
 const GATEWAY_URL = "ws://127.0.0.1:7860";
 const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "huggingclaw";
+const WHATSAPP_ENABLED = /^true$/i.test(process.env.WHATSAPP_ENABLED || "");
 const CHECK_INTERVAL = 5000;
 const WAIT_TIMEOUT = 120000;
 const POST_515_NO_LOGOUT_MS = 90 * 1000;
@@ -26,6 +25,7 @@ const RESET_MARKER_PATH = path.join(
   "workspace",
   ".reset_credentials",
 );
+const STATUS_FILE_PATH = "/tmp/huggingclaw-wa-status.json";
 
 let isWaiting = false;
 let hasShownWaitMessage = false;
@@ -36,8 +36,7 @@ let shouldStop = false;
 function extractErrorMessage(msg) {
   if (!msg || typeof msg !== "object") return "Unknown error";
   if (typeof msg.error === "string") return msg.error;
-  if (msg.error && typeof msg.error.message === "string")
-    return msg.error.message;
+  if (msg.error && typeof msg.error.message === "string") return msg.error.message;
   if (typeof msg.message === "string") return msg.message;
   return "Unknown error";
 }
@@ -46,13 +45,28 @@ function writeResetMarker() {
   try {
     fs.mkdirSync(path.dirname(RESET_MARKER_PATH), { recursive: true });
     fs.writeFileSync(RESET_MARKER_PATH, "reset\n");
-    console.log(
-      `[guardian] Created backup reset marker at ${RESET_MARKER_PATH}`,
-    );
+    console.log(`[guardian] Created backup reset marker at ${RESET_MARKER_PATH}`);
   } catch (error) {
-    console.log(
-      `[guardian] Failed to write backup reset marker: ${error.message}`,
-    );
+    console.log(`[guardian] Failed to write backup reset marker: ${error.message}`);
+  }
+}
+
+function writeStatus(partial) {
+  try {
+    const current = fs.existsSync(STATUS_FILE_PATH)
+      ? JSON.parse(fs.readFileSync(STATUS_FILE_PATH, "utf8"))
+      : {};
+    const next = {
+      configured: true,
+      connected: false,
+      pairing: false,
+      updatedAt: new Date().toISOString(),
+      ...current,
+      ...partial,
+    };
+    fs.writeFileSync(STATUS_FILE_PATH, JSON.stringify(next));
+  } catch (error) {
+    console.log(`[guardian] Failed to write status file: ${error.message}`);
   }
 }
 
@@ -65,32 +79,25 @@ async function createConnection() {
       const msg = JSON.parse(data.toString());
 
       if (msg.type === "event" && msg.event === "connect.challenge") {
-        ws.send(
-          JSON.stringify({
-            type: "req",
-            id: randomUUID(),
-            method: "connect",
-            params: {
-              minProtocol: 3,
-              maxProtocol: 3,
-              client: {
-                id: "gateway-client",
-                version: "1.0.0",
-                platform: "linux",
-                mode: "backend",
-              },
-              caps: [],
-              auth: { token: GATEWAY_TOKEN },
-              role: "operator",
-              scopes: [
-                "operator.read",
-                "operator.write",
-                "operator.admin",
-                "operator.pairing",
-              ],
+        ws.send(JSON.stringify({
+          type: "req",
+          id: randomUUID(),
+          method: "connect",
+          params: {
+            minProtocol: 3,
+            maxProtocol: 3,
+            client: {
+              id: "gateway-client",
+              version: "1.0.0",
+              platform: "linux",
+              mode: "backend",
             },
-          }),
-        );
+            caps: [],
+            auth: { token: GATEWAY_TOKEN },
+            role: "operator",
+            scopes: ["operator.read", "operator.write", "operator.admin", "operator.pairing"],
+          },
+        }));
         return;
       }
 
@@ -107,15 +114,8 @@ async function createConnection() {
       }
     });
 
-    ws.on("error", (e) => {
-      if (!resolved) reject(e);
-    });
-    setTimeout(() => {
-      if (!resolved) {
-        ws.close();
-        reject(new Error("Timeout"));
-      }
-    }, 10000);
+    ws.on("error", (e) => { if (!resolved) reject(e); });
+    setTimeout(() => { if (!resolved) { ws.close(); reject(new Error("Timeout")); } }, 10000);
   });
 }
 
@@ -135,18 +135,14 @@ async function callRpc(ws, method, params) {
     };
     ws.on("message", handler);
     ws.send(JSON.stringify({ type: "req", id, method, params }));
-    setTimeout(() => {
-      ws.removeListener("message", handler);
-      reject(new Error("RPC Timeout"));
-    }, WAIT_TIMEOUT + 5000);
+    setTimeout(() => { ws.removeListener("message", handler); reject(new Error("RPC Timeout")); }, WAIT_TIMEOUT + 5000);
   });
 }
 
 async function checkStatus() {
   if (shouldStop) return;
   if (isWaiting) return;
-  if (lastConnectedAt && Date.now() - lastConnectedAt < SUCCESS_COOLDOWN_MS)
-    return;
+  if (lastConnectedAt && Date.now() - lastConnectedAt < SUCCESS_COOLDOWN_MS) return;
 
   let ws;
   try {
@@ -158,27 +154,28 @@ async function checkStatus() {
 
     if (!wa) {
       hasShownWaitMessage = false;
+      writeStatus({ configured: true, connected: false, pairing: false });
       return;
     }
 
     if (wa.connected) {
       hasShownWaitMessage = false;
       lastConnectedAt = Date.now();
+      writeStatus({ configured: true, connected: true, pairing: false });
+      shouldStop = true;
+      setTimeout(() => process.exit(0), 1000);
       return;
     }
 
     isWaiting = true;
+    writeStatus({ configured: true, connected: false, pairing: true });
     if (!hasShownWaitMessage) {
-      console.log(
-        "\n[guardian] 📱 WhatsApp pairing in progress. Please scan the QR code in the Control UI.",
-      );
+      console.log("\n[guardian] 📱 WhatsApp pairing in progress. Please scan the QR code in the Control UI.");
       hasShownWaitMessage = true;
     }
 
     console.log("[guardian] Waiting for pairing completion...");
-    const waitRes = await callRpc(ws, "web.login.wait", {
-      timeoutMs: WAIT_TIMEOUT,
-    });
+    const waitRes = await callRpc(ws, "web.login.wait", { timeoutMs: WAIT_TIMEOUT });
     const result = waitRes.payload || waitRes.result;
     const message = result?.message || "";
     const linkedAfter515 = !result?.connected && message.includes("515");
@@ -190,41 +187,33 @@ async function checkStatus() {
     if (result && (result.connected || linkedAfter515)) {
       hasShownWaitMessage = false;
       lastConnectedAt = Date.now();
+      writeStatus({ configured: true, connected: true, pairing: false });
 
       if (linkedAfter515) {
-        console.log(
-          "[guardian] 515 after scan: credentials saved, reloading config to start WhatsApp...",
-        );
+        console.log("[guardian] 515 after scan: credentials saved, reloading config to start WhatsApp...");
       } else {
         console.log("[guardian] ✅ Pairing completed! Reloading config...");
       }
 
       const getRes = await callRpc(ws, "config.get", {});
       if (getRes.payload?.raw && getRes.payload?.hash) {
-        await callRpc(ws, "config.apply", {
-          raw: getRes.payload.raw,
-          baseHash: getRes.payload.hash,
-        });
+        await callRpc(ws, "config.apply", { raw: getRes.payload.raw, baseHash: getRes.payload.hash });
         console.log("[guardian] Configuration re-applied.");
       }
 
       shouldStop = true;
       setTimeout(() => process.exit(0), 1000);
-    } else if (
-      !message.includes("No active") &&
-      !message.includes("Still waiting")
-    ) {
+    } else if (!message.includes("No active") && !message.includes("Still waiting")) {
       console.log(`[guardian] Wait result: ${message}`);
     }
+
   } catch (e) {
     const message = e && e.message ? e.message : "";
     if (
       /401|unauthorized|logged out|440|conflict/i.test(message) &&
       Date.now() - last515At >= POST_515_NO_LOGOUT_MS
     ) {
-      console.log(
-        "[guardian] Clearing invalid WhatsApp session so a fresh QR can be used...",
-      );
+      console.log("[guardian] Clearing invalid WhatsApp session so a fresh QR can be used...");
       try {
         if (ws) {
           await callRpc(ws, "channels.logout", { channel: "whatsapp" });
@@ -233,11 +222,12 @@ async function checkStatus() {
           console.log("[guardian] Logged out invalid WhatsApp session.");
         }
       } catch (error) {
-        console.log(
-          `[guardian] Failed to log out invalid session: ${error.message}`,
-        );
+        console.log(`[guardian] Failed to log out invalid session: ${error.message}`);
       }
     }
+    if (!/RPC Timeout/i.test(message)) {
+      writeStatus({ configured: true, connected: false, pairing: false });
+    }
     // Normal timeout or gateway starting up; retry on the next interval.
   } finally {
     isWaiting = false;
@@ -245,8 +235,12 @@ async function checkStatus() {
   }
 }
 
-console.log(
-  "[guardian] ⚔️ WhatsApp Guardian active. Monitoring pairing status...",
-);
+if (!WHATSAPP_ENABLED) {
+  writeStatus({ configured: false, connected: false, pairing: false });
+  process.exit(0);
+}
+
+writeStatus({ configured: true, connected: false, pairing: false });
+console.log("[guardian] ⚔️ WhatsApp Guardian active. Monitoring pairing status...");
 setInterval(checkStatus, CHECK_INTERVAL);
 setTimeout(checkStatus, 15000);

workspace-sync.py

@@ -26,6 +26,7 @@ HF_TOKEN = os.environ.get("HF_TOKEN", "")
 HF_USERNAME = os.environ.get("HF_USERNAME", "")
 BACKUP_DATASET = os.environ.get("BACKUP_DATASET_NAME", "huggingclaw-backup")
 WEBHOOK_URL = os.environ.get("WEBHOOK_URL", "")
+WHATSAPP_ENABLED = os.environ.get("WHATSAPP_ENABLED", "").strip().lower() == "true"
 
 running = True
 
@@ -52,6 +53,9 @@ def snapshot_state_into_workspace() -> None:
     with the workspace, without changing the live credentials location.
     """
     try:
+        if not WHATSAPP_ENABLED:
+            return
+
         STATE_DIR.mkdir(parents=True, exist_ok=True)
 
         if RESET_MARKER.exists():