@lofa199419/waha-v2 2.1.0

package/index.ts

@@ -0,0 +1,109 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { wahaV2Plugin } from "./src/channel.js";
+import {
+  handleWahaV2QrRoute,
+  handleWahaV2RequestCodeRoute,
+  handleWahaV2StartRoute,
+  handleWahaV2StatusRoute,
+  handleWahaV2WaitRoute,
+  WAHA_V2_ROUTE_QR,
+  WAHA_V2_ROUTE_REQUEST_CODE,
+  WAHA_V2_ROUTE_START,
+  WAHA_V2_ROUTE_STATUS,
+  WAHA_V2_ROUTE_WAIT,
+} from "./src/routes.js";
+import { setWahaV2Runtime } from "./src/runtime.js";
+import { WAHA_V2_WEBHOOK_BASE } from "./src/types.js";
+import { handleWahaV2WebhookRequest } from "./src/webhook.js";
+
+const plugin = {
+  id: "waha-v2",
+  name: "WAHA v2 (WhatsApp HTTP API)",
+  configSchema: emptyPluginConfigSchema(),
+  description:
+    "Independent WAHA WhatsApp HTTP API channel plugin. " +
+    "Uses waha-node for outbound; OpenClaw plugin-sdk for inbound, routing, and policies.",
+
+  register(api: OpenClawPluginApi) {
+    // Store the runtime and logger for use in the webhook handler, gateway, and routes.
+    setWahaV2Runtime(api.runtime, api.logger);
+
+    // Register the channel (config, gateway, outbound, status, etc.).
+    api.registerChannel({ plugin: wahaV2Plugin });
+
+    // Inbound webhook — matches both:
+    //   /webhooks/waha-v2             (legacy, routes by session name in payload)
+    //   /webhooks/waha-v2/{accountId} (preferred, unambiguous — accountId from path)
+    // Newer OpenClaw plugin SDK requires explicit route auth and no longer supports
+    // registerHttpHandler or dynamic path params in plugin routes.
+    api.registerHttpRoute({
+      path: WAHA_V2_WEBHOOK_BASE,
+      auth: "plugin",
+      match: "prefix",
+      handler: async (req, res) => {
+        const url = req.url ?? "";
+        if (!url.startsWith(WAHA_V2_WEBHOOK_BASE)) {
+          return false;
+        }
+        const suffix = url.slice(WAHA_V2_WEBHOOK_BASE.length).split("?")[0] ?? "";
+        const accountId = suffix.startsWith("/") ? suffix.slice(1) || undefined : undefined;
+        await handleWahaV2WebhookRequest(req, res, api.runtime.config.loadConfig(), accountId);
+        return true;
+      },
+    });
+
+    // Session management API routes — used by UI, CLI, and setup flows.
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_STATUS,
+      auth: "gateway",
+      match: "exact",
+      handler: async (req, res) => {
+        await handleWahaV2StatusRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_START,
+      auth: "gateway",
+      match: "exact",
+      handler: async (req, res) => {
+        await handleWahaV2StartRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_QR,
+      auth: "gateway",
+      match: "exact",
+      handler: async (req, res) => {
+        await handleWahaV2QrRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_REQUEST_CODE,
+      auth: "gateway",
+      match: "exact",
+      handler: async (req, res) => {
+        await handleWahaV2RequestCodeRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_WAIT,
+      auth: "gateway",
+      match: "exact",
+      handler: async (req, res) => {
+        await handleWahaV2WaitRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.logger.info(
+      `waha-v2: registered channel + webhook ${WAHA_V2_WEBHOOK_BASE}/{accountId} + ` +
+        `session API routes (status, start, qr, request-code, wait)`,
+    );
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "waha-v2",
+  "channels": ["waha-v2"],
+  "skills": ["skills/waha-v2", "skills/waha-v2-onboarding"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lofa199419/waha-v2",
+  "version": "2.1.0",
+  "private": false,
+  "description": "OpenClaw WAHA v2 channel plugin — independent WhatsApp HTTP API integration",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "skills",
+    "bin/waha-cli",
+    "bin/wa",
+    "bin/wa-adv",
+    "bin/waha-advanced-entrypoint",
+    "bin/waha_cli.py",
+    "scripts/install-openclaw-extension.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "pack:check": "npm pack --dry-run",
+    "install:openclaw": "node scripts/install-openclaw-extension.mjs"
+  },
+  "dependencies": {
+    "axios": "1.6.0",
+    "waha-node": "1.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "waha-v2",
+      "label": "WAHA",
+      "selectionLabel": "WAHA v2 (plugin)",
+      "detailLabel": "WAHA v2",
+      "docsPath": "/channels/whatsapp",
+      "docsLabel": "whatsapp",
+      "blurb": "Independent WAHA WhatsApp HTTP API plugin — no Baileys dependency.",
+      "order": 13,
+      "systemImage": "qrcode"
+    },
+    "install": {
+      "npmSpec": "@lofa199419/waha-v2",
+      "localPath": "extensions/waha-v2",
+      "script": "node scripts/install-openclaw-extension.mjs",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/scripts/install-openclaw-extension.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const packageRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+function parseArgs(argv) {
+  const out = {
+    stateDir: process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || "", ".openclaw"),
+    force: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--state-dir") {
+      out.stateDir = argv[i + 1];
+      i += 1;
+    } else if (arg === "--force") {
+      out.force = true;
+    } else if (arg === "--help" || arg === "-h") {
+      out.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(target) {
+  await fs.mkdir(target, { recursive: true });
+}
+
+async function copyFile(relPath, destinationRoot) {
+  const source = path.join(packageRoot, relPath);
+  const destination = path.join(destinationRoot, relPath);
+  await ensureDir(path.dirname(destination));
+  await fs.copyFile(source, destination);
+  const stat = await fs.stat(source);
+  await fs.chmod(destination, stat.mode);
+}
+
+async function copyDirectory(relPath, destinationRoot) {
+  const source = path.join(packageRoot, relPath);
+  const destination = path.join(destinationRoot, relPath);
+  await ensureDir(path.dirname(destination));
+  await fs.cp(source, destination, { recursive: true, force: true });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log("Usage: node scripts/install-openclaw-extension.mjs [--state-dir PATH] [--force]");
+    process.exit(0);
+  }
+
+  if (!args.stateDir) {
+    throw new Error("Missing OpenClaw state dir. Pass --state-dir or set OPENCLAW_STATE_DIR.");
+  }
+
+  const extensionRoot = path.join(args.stateDir, "extensions", "waha-v2");
+  if (await exists(extensionRoot)) {
+    if (!args.force) {
+      throw new Error(`Target already exists: ${extensionRoot}. Re-run with --force to replace it.`);
+    }
+    await fs.rm(extensionRoot, { recursive: true, force: true });
+  }
+
+  await ensureDir(extensionRoot);
+
+  const directories = ["src", "skills", "scripts"];
+  const files = [
+    "index.ts",
+    "openclaw.plugin.json",
+    "package.json",
+    "README.md",
+    "bin/waha-cli",
+    "bin/wa",
+    "bin/wa-adv",
+    "bin/waha-advanced-entrypoint",
+    "bin/waha_cli.py",
+  ];
+
+  for (const relPath of directories) {
+    await copyDirectory(relPath, extensionRoot);
+  }
+  for (const relPath of files) {
+    await copyFile(relPath, extensionRoot);
+  }
+
+  console.log(`Installed waha-v2 into ${extensionRoot}`);
+}
+
+main().catch((error) => {
+  console.error(`[waha-v2 install] ${error.message}`);
+  process.exit(1);
+});

package/skills/waha-v2/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: waha-v2
+description: "Operate WhatsApp for OpenClaw using one local MCP CLI (advanced) for all WAHA API operations; use gateway only for inbound webhooks and outbound `message` sends."
+metadata: { "openclaw": { "emoji": "💬", "requires": { "config": ["channels.waha-v2"] } } }
+allowed-tools: ["exec", "message"]
+---
+
+# WAHA v2 — Advanced CLI Operation Mode
+
+Use this skill to run WhatsApp actions through the local advanced binary, not through gateway routing actions.
+
+## Routing Rule (strict)
+
+- **Gateway remains only for:**
+  1. **Receiving inbound WhatsApp events** via webhook.
+  2. **Sending outbound chat replies** via OpenClaw `message` tool (`channel: "waha-v2"`).
+- **Do not use gateway action routing for WAHA operations** (sessions, auth, chats, groups, contacts, channels, status, etc.).
+- For WAHA operational tasks, use local CLI via `exec`.
+
+## Single CLI (use this only)
+
+- Resolve the OpenClaw state dir first:
+  - `STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"`
+- Wrapper (preferred):
+  - `"$STATE_DIR/extensions/waha-v2/bin/waha-cli"`
+- Convenience wrapper that auto-adds `--session` when configured:
+  - `"$STATE_DIR/extensions/waha-v2/bin/wa"`
+
+## Environment handling
+
+- Primary config source:
+  - `"$STATE_DIR/openclaw.json"` -> `channels.waha-v2`
+- Fallback config source:
+  - `"$STATE_DIR/extensions/waha-v2/bin/.env"`
+- The CLI now resolves config in this order:
+  1. `channels.waha-v2` in `openclaw.json`
+  2. process environment
+  3. `bin/.env`
+- Agents should call the installed wrapper directly and should not assume `/data/.openclaw/...`.
+
+## Fast tutorial
+
+### 1) Discover commands
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" --help
+```
+
+### 2) Session/auth flow
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-list-sessions
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-create-session --name finalhope
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-get-qr-code --session finalhope
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-request-pairing-code --session finalhope --phone-number 31612345678
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-check-auth-status --session finalhope
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-logout-session --session finalhope
+```
+
+### 3) Chats/messages
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-get-chats --limit 20
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-get-messages --chat-id 15550001234@c.us --limit 30
+"$STATE_DIR/extensions/waha-v2/bin/waha-cli" waha-send-text --chat-id 15550001234@c.us --text "Hello"
+```
+
+### 4) Outbound user-visible send (official OpenClaw path)
+
+Use `message` tool for final user-facing sends:
+
+```json
+{ "action": "send", "channel": "waha-v2", "to": "15550001234@c.us", "message": "Hello!" }
+```
+
+## IDs and formatting
+
+- Direct chat: `<digits>@c.us`
+- Group: `<digits>@g.us`
+- Strip non-digits before building `@c.us` IDs.
+
+## Operational notes
+
+- Keep replies complete (no streaming partials).
+- Confirm destructive actions before execution when user intent is ambiguous.
+
+---
+
+## Exemplary Scenario: New User WhatsApp Onboarding
+
+This is a real end-to-end flow completed successfully (2026-03-22).
+
+### Flow
+
+**Step 1 — Greet and collect number**
+> "Welcome! To get you connected, I need your WhatsApp phone number (include country code, no spaces — e.g. `31612345678`)."
+
+**Step 2 — Create and start session**
+```bash
+waha-cli waha-create-session --name user-<phonenumber>
+waha-cli waha-start-session --session user-<phonenumber>
+```
+Wait ~5 seconds for session to initialize before requesting pairing code.
+
+**Step 3 — Request pairing code**
+```bash
+waha-cli waha-request-pairing-code --session user-<phonenumber> --phone-number <phonenumber>
+# → Code: VB4R-3LKL  (example)
+```
+
+**Step 4 — Share code with user**
+> "Here's your code: `VB4R-3LKL`
+> On your phone: WhatsApp → ⋮ → Linked Devices → Link a Device → Link with phone number instead → enter the code."
+
+**Step 5 — Wait for user confirmation, then verify**
+```bash
+waha-cli waha-check-auth-status --session user-<phonenumber>
+# → Status: WORKING | Account ID: <phonenumber>@c.us | Name: <display name>
+```
+
+**Step 6 — Confirm and offer next actions**
+> "You're in! Want me to pull up recent conversations, browse contacts, or read a specific chat?"
+
+---
+
+### Fallback: if pairing code fails
+
+If status is not `WORKING` after user enters the code:
+
+```bash
+waha-cli waha-start-session --session user-<phonenumber>   # restart for fresh QR state
+# wait ~5s
+waha-cli waha-request-pairing-code --session user-<phonenumber> --phone-number <phonenumber>
+# share new code — second attempt typically succeeds
+```
+
+---
+
+### Session naming convention
+Use `user-<phonenumber>` (e.g. `user-905380546393`) to avoid collisions and keep sessions identifiable.

package/skills/waha-v2-onboarding/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: waha-v2-onboarding
+description: "Onboard a new WhatsApp user onto WAHA by creating a session, requesting a pairing code, verifying login, and confirming readiness."
+metadata: { "openclaw": { "emoji": "🔐", "requires": { "config": ["channels.waha-v2"] } } }
+allowed-tools: ["exec", "message"]
+---
+
+# WAHA v2 — User Onboarding And Login
+
+Use this skill when the goal is to connect a new WhatsApp account to WAHA and confirm the session is usable.
+
+## Scope
+
+- Create a session for the user
+- Start or restart that session
+- Request a pairing code
+- Guide the user through entering the code
+- Verify the session reaches `WORKING`
+
+Do not use this skill for general chat browsing or operational WAHA admin work unless it directly supports onboarding.
+
+## Binary Resolution
+
+Always resolve the installed extension from the OpenClaw state dir:
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+WAHA_BIN="$STATE_DIR/extensions/waha-v2/bin/waha-cli"
+```
+
+The CLI resolves config from:
+1. `"$STATE_DIR/openclaw.json"` -> `channels.waha-v2`
+2. process environment
+3. `"$STATE_DIR/extensions/waha-v2/bin/.env"`
+
+## Session Naming
+
+Use:
+
+```text
+user-<phonenumber>
+```
+
+Example:
+
+```text
+user-905380546393
+```
+
+Use digits only, including country code, with no spaces or `+`.
+
+## Standard Flow
+
+### 1) Collect phone number
+
+Ask the user for their WhatsApp number in international format without spaces or `+`.
+
+Example:
+
+> "To connect your WhatsApp, send your phone number with country code, digits only. Example: `31612345678`."
+
+### 2) Create and start session
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+WAHA_BIN="$STATE_DIR/extensions/waha-v2/bin/waha-cli"
+SESSION="user-<phonenumber>"
+
+"$WAHA_BIN" waha-create-session --name "$SESSION"
+"$WAHA_BIN" waha-start-session --session "$SESSION"
+```
+
+Wait about 5 seconds after start before requesting pairing code.
+
+### 3) Request pairing code
+
+```bash
+"$WAHA_BIN" waha-request-pairing-code --session "$SESSION" --phone-number <phonenumber>
+```
+
+Expected output includes:
+
+```text
+Code: XXXX-XXXX
+```
+
+### 4) Instruct the user
+
+Send the code and tell the user to enter it in WhatsApp:
+
+> "Open WhatsApp on your phone: Linked Devices -> Link a Device -> Link with phone number instead -> enter this code: `<code>`"
+
+### 5) Verify session status
+
+```bash
+"$WAHA_BIN" waha-check-auth-status --session "$SESSION"
+```
+
+Success means:
+
+```text
+Status: WORKING
+```
+
+If present, capture:
+- `Account ID`
+- `Name`
+
+### 6) Confirm completion
+
+Example:
+
+> "Your WhatsApp session is connected. I can now help with chats, contacts, or other WAHA operations."
+
+## Fallback Flow
+
+If pairing does not complete:
+
+```bash
+"$WAHA_BIN" waha-start-session --session "$SESSION"
+# wait ~5s
+"$WAHA_BIN" waha-request-pairing-code --session "$SESSION" --phone-number <phonenumber>
+```
+
+If status remains `SCAN_QR_CODE`, explain that the session is waiting for the pairing step to finish.
+
+## Operational Rules
+
+- Prefer pairing code flow over QR when the user is already in chat with the agent.
+- Do not rename session ids once created.
+- Do not delete or log out an existing user session unless the user explicitly asks.
+- Confirm destructive actions before executing them.
+- Keep user-facing instructions short and exact.
+
+## Quick Commands
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+WAHA_BIN="$STATE_DIR/extensions/waha-v2/bin/waha-cli"
+SESSION="user-905380546393"
+
+"$WAHA_BIN" waha-create-session --name "$SESSION"
+"$WAHA_BIN" waha-start-session --session "$SESSION"
+"$WAHA_BIN" waha-request-pairing-code --session "$SESSION" --phone-number 905380546393
+"$WAHA_BIN" waha-check-auth-status --session "$SESSION"
+```