@lofa199419/waha-v2 2026.3.2

package/index.ts

@@ -0,0 +1,92 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { wahaV2Plugin } from "./src/channel.js";
+import { setWahaV2Runtime } from "./src/runtime.js";
+import { handleWahaV2WebhookRequest } from "./src/webhook.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 { WAHA_V2_WEBHOOK_BASE } from "./src/types.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)
+    // Using registerHttpHandler so we can capture the dynamic {accountId} segment.
+    api.registerHttpHandler(async (req, res) => {
+      const url = req.url ?? "";
+      if (!url.startsWith(WAHA_V2_WEBHOOK_BASE)) return false;
+      // Extract optional accountId from the path suffix.
+      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,
+      handler: async (req, res) => {
+        await handleWahaV2StatusRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_START,
+      handler: async (req, res) => {
+        await handleWahaV2StartRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_QR,
+      handler: async (req, res) => {
+        await handleWahaV2QrRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_REQUEST_CODE,
+      handler: async (req, res) => {
+        await handleWahaV2RequestCodeRoute(req, res, api.runtime.config.loadConfig());
+      },
+    });
+
+    api.registerHttpRoute({
+      path: WAHA_V2_ROUTE_WAIT,
+      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"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lofa199419/waha-v2",
+  "version": "2026.3.2",
+  "private": false,
+  "description": "OpenClaw WAHA v2 channel plugin — independent WhatsApp HTTP API integration",
+  "type": "module",
+  "dependencies": {
+    "axios": "1.6.0",
+    "waha-node": "1.0.0"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "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",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/skills/waha-v2/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: waha-v2
+description: "Full WhatsApp agent via WAHA HTTP API — send messages, read chat history, manage contacts, groups, status stories, and WA channels."
+metadata: { "openclaw": { "emoji": "💬", "requires": { "config": ["channels.waha-v2"] } } }
+allowed-tools: ["message"]
+---
+
+# WAHA v2 — Full WhatsApp Agent
+
+Use the `message` tool with `channel: "waha-v2"`. You have complete WhatsApp access: messaging, chat history, contacts, groups, status stories, and WhatsApp Channels.
+
+## Musts
+
+- Always set `channel: "waha-v2"`.
+- Phone numbers as JIDs: `"<digits>@c.us"` for DMs, `"<digits>@g.us"` for groups.
+- Strip all non-digits before appending `@c.us` (e.g. `+1 (555) 000-1234` → `"15550001234@c.us"`).
+- Never send streaming or partial text to WhatsApp — only send the final, complete reply.
+- Multi-account: pass `accountId` when the user has more than one WAHA instance configured.
+
+## Session States
+
+| State | Meaning |
+|---|---|
+| `WORKING` / `CONNECTED` | Ready — go ahead |
+| `STOPPED` / `FAILED` | Call `start-session` first |
+| `SCAN_QR_CODE` / `PAIRING` | Waiting for user to scan QR or enter code |
+| `CONNECTING` | Starting up — wait briefly |
+
+---
+
+## Sending Messages
+
+### Text
+```json
+{ "action": "send", "channel": "waha-v2", "to": "15550001234@c.us", "message": "Hello!" }
+```
+
+### Media (image / video / audio / file)
+```json
+{ "action": "send", "channel": "waha-v2", "to": "15550001234@c.us", "media": "https://…/file.pdf", "message": "Your report" }
+```
+
+### Poll
+```json
+{ "action": "poll", "channel": "waha-v2", "to": "15550001234@c.us", "pollQuestion": "Which day?", "pollOption": ["Mon","Wed","Fri"], "pollMulti": false }
+```
+
+### Location
+```json
+{ "action": "send-location", "channel": "waha-v2", "to": "15550001234@c.us", "latitude": 37.77, "longitude": -122.41, "title": "SF Office" }
+```
+
+### Contact card
+```json
+{ "action": "send-contact", "channel": "waha-v2", "to": "15550001234@c.us", "contacts": [{ "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Alice\nTEL:+14155559999\nEND:VCARD" }] }
+```
+
+### Forward a message
+```json
+{ "action": "forward-message", "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+```
+
+---
+
+## Message Management
+
+```json
+{ "action": "react",          "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>", "emoji": "👍" }
+{ "action": "send-seen",      "channel": "waha-v2", "to": "15550001234@c.us" }
+{ "action": "edit",           "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>", "text": "corrected" }
+{ "action": "delete",         "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+{ "action": "pin",            "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+{ "action": "unpin",          "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+{ "action": "star-message",   "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+{ "action": "unstar-message", "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+```
+
+---
+
+## Reading Chat History
+
+```json
+{ "action": "list-chats",         "channel": "waha-v2", "limit": 50 }
+{ "action": "get-chat-messages",  "channel": "waha-v2", "to": "15550001234@c.us", "limit": 30 }
+{ "action": "get-message",        "channel": "waha-v2", "to": "15550001234@c.us", "messageId": "<id>" }
+```
+
+## Chat Management
+
+```json
+{ "action": "archive-chat",     "channel": "waha-v2", "to": "15550001234@c.us" }
+{ "action": "unarchive-chat",   "channel": "waha-v2", "to": "15550001234@c.us" }
+{ "action": "delete-chat",      "channel": "waha-v2", "to": "15550001234@c.us" }
+{ "action": "mark-chat-unread", "channel": "waha-v2", "to": "15550001234@c.us" }
+```
+
+---
+
+## Contacts
+
+```json
+{ "action": "list-contacts",   "channel": "waha-v2", "limit": 100 }
+{ "action": "get-contact",     "channel": "waha-v2", "contactId": "15550001234@c.us" }
+{ "action": "check-contact",   "channel": "waha-v2", "phone": "15550001234" }
+{ "action": "block-contact",   "channel": "waha-v2", "to": "15550001234@c.us" }
+{ "action": "unblock-contact", "channel": "waha-v2", "to": "15550001234@c.us" }
+```
+
+---
+
+## Groups
+
+```json
+{ "action": "list-groups",                "channel": "waha-v2" }
+{ "action": "get-group",                  "channel": "waha-v2", "groupId": "120363012345@g.us" }
+{ "action": "create-group",               "channel": "waha-v2", "subject": "Team Sync", "participants": ["15550001234@c.us"] }
+{ "action": "get-group-participants",     "channel": "waha-v2", "groupId": "120363012345@g.us" }
+{ "action": "add-group-participants",     "channel": "waha-v2", "groupId": "120363012345@g.us", "participants": ["15550001234@c.us"] }
+{ "action": "remove-group-participants",  "channel": "waha-v2", "groupId": "120363012345@g.us", "participants": ["15550001234@c.us"] }
+{ "action": "promote-group-admin",        "channel": "waha-v2", "groupId": "120363012345@g.us", "participants": ["15550001234@c.us"] }
+{ "action": "demote-group-admin",         "channel": "waha-v2", "groupId": "120363012345@g.us", "participants": ["15550001234@c.us"] }
+{ "action": "renameGroup",                "channel": "waha-v2", "groupId": "120363012345@g.us", "name": "New Name" }
+{ "action": "update-group-description",   "channel": "waha-v2", "groupId": "120363012345@g.us", "description": "Weekly standups" }
+{ "action": "get-group-invite-code",      "channel": "waha-v2", "groupId": "120363012345@g.us" }
+{ "action": "revoke-group-invite-code",   "channel": "waha-v2", "groupId": "120363012345@g.us" }
+{ "action": "leaveGroup",                 "channel": "waha-v2", "groupId": "120363012345@g.us" }
+```
+
+---
+
+## Status / Stories
+
+```json
+{ "action": "send-status",   "channel": "waha-v2", "text": "Good morning! 🌅" }
+{ "action": "delete-status", "channel": "waha-v2", "messageId": "<statusMessageId>" }
+```
+
+---
+
+## WhatsApp Channels (Newsletters)
+
+```json
+{ "action": "list-wa-channels",        "channel": "waha-v2" }
+{ "action": "get-wa-channel",          "channel": "waha-v2", "channelId": "<id>" }
+{ "action": "create-wa-channel",       "channel": "waha-v2", "name": "My Channel", "description": "Daily updates" }
+{ "action": "get-wa-channel-messages", "channel": "waha-v2", "channelId": "<id>", "limit": 20 }
+{ "action": "delete-wa-channel",       "channel": "waha-v2", "channelId": "<id>" }
+```
+
+---
+
+## Session Management & Login Flow
+
+### Full QR login sequence
+1. `start-session` — if `alreadyConnected: true`, done.
+2. `get-qr` — returns `{ data }` base64 PNG; show to user to scan in WhatsApp → Linked Devices.
+3. User scans, then call `start-session` again to confirm `connected: true`.
+
+### Pairing code (no phone camera)
+1. `start-session`
+2. `request-code` with `phoneNumber: "15550001234"` — returns 8-digit code.
+3. User enters code in WhatsApp → Linked Devices → Link with phone number.
+4. `start-session` to confirm.
+
+```json
+{ "action": "logout-session", "channel": "waha-v2" }
+```
+
+---
+
+## Multi-Account
+
+```json
+{ "action": "send", "channel": "waha-v2", "accountId": "secondary", "to": "15550001234@c.us", "message": "Hi" }
+```
+
+Each account gets its own webhook: `{webhookUrl}/{accountId}`.
+
+---
+
+## WhatsApp Markdown
+
+`*bold*` `_italic_` `~strikethrough~` `` `mono` `` — no HTML, no tables.

package/src/accounts.ts

@@ -0,0 +1,117 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  WAHA_V2_CHANNEL_ID,
+  WAHA_V2_DEFAULT_ACCOUNT_ID,
+  type ResolvedWahaV2Account,
+  type WahaV2AccountConfig,
+  type WahaV2RootConfig,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Config extraction
+// ---------------------------------------------------------------------------
+
+export function readWahaV2Root(cfg: OpenClawConfig): WahaV2RootConfig {
+  const channels = (cfg as Record<string, unknown>).channels;
+  if (!channels || typeof channels !== "object" || Array.isArray(channels)) {
+    return {};
+  }
+  const root = (channels as Record<string, unknown>)[WAHA_V2_CHANNEL_ID];
+  if (!root || typeof root !== "object" || Array.isArray(root)) {
+    return {};
+  }
+  return root as WahaV2RootConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Account list
+// ---------------------------------------------------------------------------
+
+export function listWahaV2AccountIds(cfg: OpenClawConfig): string[] {
+  const root = readWahaV2Root(cfg);
+  const ids = Object.keys(root.accounts ?? {}).filter(Boolean);
+  // If no named accounts are configured, expose a single implicit "default" account.
+  return ids.length > 0 ? ids.toSorted((a, b) => a.localeCompare(b)) : [WAHA_V2_DEFAULT_ACCOUNT_ID];
+}
+
+// ---------------------------------------------------------------------------
+// Account resolution — account-level fields override root-level
+// ---------------------------------------------------------------------------
+
+export function resolveWahaV2Account(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedWahaV2Account {
+  const resolvedId = accountId?.trim() || WAHA_V2_DEFAULT_ACCOUNT_ID;
+  const root = readWahaV2Root(cfg);
+  // Merge: root provides defaults; per-account config overrides.
+  const account: WahaV2AccountConfig =
+    resolvedId === WAHA_V2_DEFAULT_ACCOUNT_ID
+      ? root
+      : { ...root, ...(root.accounts?.[resolvedId] ?? {}) };
+
+  return {
+    accountId: resolvedId,
+    name: account.name?.trim() || undefined,
+    baseUrl: account.baseUrl?.trim() || "http://localhost:3000",
+    apiKey: account.apiKey?.trim() || "",
+    session: account.session?.trim() || "default",
+    webhookUrl: account.webhookUrl?.trim() || undefined,
+    enabled: account.enabled !== false,
+    dmPolicy: account.dmPolicy,
+    allowFrom: account.allowFrom,
+  };
+}
+
+/** Find the account whose session name matches the given WAHA session string. */
+export function resolveWahaV2AccountBySession(
+  cfg: OpenClawConfig,
+  session: string,
+): ResolvedWahaV2Account | undefined {
+  for (const accountId of listWahaV2AccountIds(cfg)) {
+    const account = resolveWahaV2Account(cfg, accountId);
+    if (account.session === session.trim()) {
+      return account;
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Config mutation helpers (used by ChannelConfigAdapter)
+// ---------------------------------------------------------------------------
+
+export function setWahaV2ChannelConfig(
+  cfg: OpenClawConfig,
+  patch: Partial<WahaV2RootConfig>,
+): OpenClawConfig {
+  const base = cfg as Record<string, unknown>;
+  const channels = { ...((base.channels as Record<string, unknown>) ?? {}) };
+  const current = (channels[WAHA_V2_CHANNEL_ID] ?? {}) as Record<string, unknown>;
+  channels[WAHA_V2_CHANNEL_ID] = { ...current, ...patch };
+  return { ...base, channels } as OpenClawConfig;
+}
+
+export function setWahaV2AccountEnabled(
+  cfg: OpenClawConfig,
+  accountId: string,
+  enabled: boolean,
+): OpenClawConfig {
+  const root = readWahaV2Root(cfg);
+  if (accountId === WAHA_V2_DEFAULT_ACCOUNT_ID && !root.accounts?.[accountId]) {
+    // Single-account mode — set enabled on root.
+    return setWahaV2ChannelConfig(cfg, { ...root, enabled });
+  }
+  const accounts = { ...(root.accounts ?? {}), [accountId]: { ...(root.accounts?.[accountId] ?? {}), enabled } };
+  return setWahaV2ChannelConfig(cfg, { ...root, accounts });
+}
+
+export function deleteWahaV2Account(cfg: OpenClawConfig, accountId: string): OpenClawConfig {
+  const root = readWahaV2Root(cfg);
+  if (!root.accounts?.[accountId]) {
+    return cfg;
+  }
+  const accounts = { ...root.accounts };
+  delete accounts[accountId];
+  return setWahaV2ChannelConfig(cfg, { ...root, accounts: Object.keys(accounts).length > 0 ? accounts : undefined });
+}