@lofa199419/waha-v2 2.1.0

package/src/channel.ts

@@ -0,0 +1,823 @@
+import type { ChannelMessageActionName, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
+import { createActionGate, jsonResult } from "openclaw/plugin-sdk";
+import {
+  deleteWahaV2Account,
+  listWahaV2AccountIds,
+  readWahaV2Root,
+  resolveWahaV2Account,
+  setWahaV2AccountEnabled,
+  setWahaV2ChannelConfig,
+} from "./accounts.js";
+import { wahaV2ChannelConfigSchema } from "./config-schema.js";
+import { wahaV2Gateway } from "./gateway.js";
+import { acquireLoginLock, releaseLoginLock, waitForWahaV2Connected } from "./login.js";
+import { wahaV2Outbound } from "./outbound.js";
+import { probeWahaV2Session } from "./probe.js";
+import { getWahaV2Client } from "./runtime.js";
+import {
+  WAHA_V2_CHANNEL_ID,
+  WAHA_V2_DEFAULT_ACCOUNT_ID,
+  type ResolvedWahaV2Account,
+  type WahaV2ActionConfig,
+  type WahaV2RootConfig,
+} from "./types.js";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function prepareSessionForRequestCode(params: {
+  client: NonNullable<ReturnType<typeof getWahaV2Client>>;
+  session: string;
+}): Promise<{
+  sessionExisted: boolean;
+  previousStatus: string | null;
+  restarted: boolean;
+}> {
+  const sessions = await params.client.listSessions(true).catch(() => []);
+  const current = sessions.find((entry) => String(entry?.name ?? "") === params.session);
+  const previousStatus = current && typeof current.status === "string" ? current.status : null;
+  const sessionExisted = Boolean(current);
+  let restarted = false;
+
+  if (!sessionExisted) {
+    await params.client.createSession(params.session);
+    await params.client.startSession(params.session);
+    return { sessionExisted, previousStatus, restarted };
+  }
+
+  const normalized = String(previousStatus ?? "").trim().toUpperCase();
+  const shouldRestart =
+    normalized.length > 0 &&
+    !["STOPPED", "FAILED", "NONE", "UNKNOWN", "DISCONNECTED"].includes(normalized);
+
+  if (shouldRestart) {
+    await params.client.stopSession(params.session).catch(() => {});
+    restarted = true;
+  }
+
+  await params.client.startSession(params.session).catch(async () => {
+    await params.client.createSession(params.session);
+    await params.client.startSession(params.session);
+  });
+
+  return { sessionExisted, previousStatus, restarted };
+}
+
+/** Normalize allow-from entries to WhatsApp JID format. */
+function normalizeAllowEntry(entry: string): string {
+  const trimmed = entry.trim();
+  if (trimmed.includes("@")) return trimmed;
+  return `${trimmed.replace(/\D+/g, "")}@c.us`;
+}
+
+const ALL_ACTIONS = [
+  // Session management
+  "start-session",
+  "get-qr",
+  "request-code",
+  "logout-session",
+  // Message actions
+  "react",
+  "send-seen",
+  "send-location",
+  "send-contact",
+  "forward-message",
+  "star-message",
+  "unstar-message",
+  "edit",
+  "delete",
+  "pin",
+  "unpin",
+  // Chats
+  "list-chats",
+  "get-chat-messages",
+  "get-message",
+  "archive-chat",
+  "unarchive-chat",
+  "delete-chat",
+  "mark-chat-unread",
+  // Contacts
+  "list-contacts",
+  "get-contact",
+  "check-contact",
+  "block-contact",
+  "unblock-contact",
+  // Groups
+  "list-groups",
+  "get-group",
+  "create-group",
+  "get-group-participants",
+  "add-group-participants",
+  "remove-group-participants",
+  "promote-group-admin",
+  "demote-group-admin",
+  "get-group-invite-code",
+  "revoke-group-invite-code",
+  "renameGroup",
+  "update-group-description",
+  "leaveGroup",
+  "addParticipant",
+  "removeParticipant",
+  // Status / Stories
+  "send-status",
+  "delete-status",
+  // WA Channels (newsletters)
+  "list-wa-channels",
+  "get-wa-channel",
+  "create-wa-channel",
+  "delete-wa-channel",
+  "get-wa-channel-messages",
+] as const;
+
+export const wahaV2Plugin: ChannelPlugin<ResolvedWahaV2Account> = {
+  id: WAHA_V2_CHANNEL_ID,
+
+  meta: {
+    id: WAHA_V2_CHANNEL_ID,
+    label: "WAHA (WhatsApp HTTP API)",
+    selectionLabel: "WAHA v2 — WhatsApp via HTTP API",
+    docsPath: "/channels/whatsapp",
+    blurb: "Self-hosted WhatsApp HTTP API; bring your own WAHA instance. No Baileys dependency.",
+    order: 13,
+    aliases: ["waha-v2", "waha2"],
+    quickstartAllowFrom: true,
+  },
+
+  configSchema: wahaV2ChannelConfigSchema,
+
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: true,
+    polls: true,
+    threads: false,
+  },
+
+  config: {
+    listAccountIds: listWahaV2AccountIds,
+    resolveAccount: resolveWahaV2Account,
+    defaultAccountId: () => WAHA_V2_DEFAULT_ACCOUNT_ID,
+
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setWahaV2AccountEnabled(cfg, accountId, enabled),
+
+    deleteAccount: ({ cfg, accountId }) => deleteWahaV2Account(cfg, accountId),
+
+    isEnabled: (account) => account.enabled,
+
+    isConfigured: (account) => Boolean(account.baseUrl && account.apiKey),
+
+    unconfiguredReason: () =>
+      "Set channels.waha-v2.apiKey via `openclaw config set channels.waha-v2.apiKey <key>`",
+
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.baseUrl && account.apiKey),
+      linked: Boolean(account.baseUrl && account.apiKey),
+      connected: false, // live value supplied by status.buildAccountSnapshot
+      baseUrl: account.baseUrl,
+      webhookUrl: account.webhookUrl,
+      dmPolicy: account.dmPolicy,
+      groupPolicy: account.groupPolicy,
+      allowFrom: account.allowFrom,
+      allowGroups: account.allowGroups,
+    }),
+
+    resolveAllowFrom: ({ cfg, accountId }) => resolveWahaV2Account(cfg, accountId).allowFrom,
+
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((e) => normalizeAllowEntry(String(e))).filter(Boolean),
+  },
+
+  setup: {
+    applyAccountConfig: ({ cfg, input }) => {
+      const root = readWahaV2Root(cfg);
+      return setWahaV2ChannelConfig(cfg, {
+        ...root,
+        ...(input.token ? { apiKey: input.token } : {}),
+        ...(input.httpUrl ? { baseUrl: input.httpUrl } : {}),
+        ...(input.name ? { session: input.name } : {}),
+        enabled: true,
+      });
+    },
+  },
+
+  pairing: {
+    idLabel: "WhatsApp number",
+    normalizeAllowEntry,
+  },
+
+  messaging: {
+    normalizeTarget: (to: string) => {
+      const trimmed = to.trim();
+      if (trimmed.includes("@")) return trimmed;
+      return `${trimmed.replace(/\D+/g, "")}@c.us`;
+    },
+    targetResolver: {
+      looksLikeId: (id: string) => /^\d{7,15}(@[cg]\.us)?$/.test(id.trim()),
+      hint: "<E.164 | group JID>",
+    },
+  },
+
+  actions: {
+    listActions: ({ cfg }) => {
+      const root = ((cfg as Record<string, unknown>)?.channels as Record<string, unknown>)?.[
+        WAHA_V2_CHANNEL_ID
+      ] as WahaV2RootConfig | undefined;
+      const gate = createActionGate(root?.actions as WahaV2ActionConfig | undefined);
+      const result: ChannelMessageActionName[] = [];
+      // Session management
+      if (gate("sessionManagement")) {
+        result.push("start-session", "get-qr", "request-code", "logout-session");
+      }
+      // Message-level actions
+      if (gate("messaging")) {
+        result.push(
+          "react",
+          "send-seen",
+          "send-location",
+          "send-contact",
+          "forward-message",
+          "star-message",
+          "unstar-message",
+          "edit",
+          "delete",
+          "pin",
+          "unpin",
+        );
+      }
+      // Chat browsing / management
+      if (gate("chats")) {
+        result.push(
+          "list-chats",
+          "get-chat-messages",
+          "get-message",
+          "archive-chat",
+          "unarchive-chat",
+          "delete-chat",
+          "mark-chat-unread",
+        );
+      }
+      // Contact lookup / block
+      if (gate("contacts")) {
+        result.push(
+          "list-contacts",
+          "get-contact",
+          "check-contact",
+          "block-contact",
+          "unblock-contact",
+        );
+      }
+      // Group management
+      if (gate("groups")) {
+        result.push(
+          "list-groups",
+          "get-group",
+          "create-group",
+          "get-group-participants",
+          "add-group-participants",
+          "remove-group-participants",
+          "promote-group-admin",
+          "demote-group-admin",
+          "get-group-invite-code",
+          "revoke-group-invite-code",
+          "renameGroup",
+          "update-group-description",
+          "leaveGroup",
+          "addParticipant",
+          "removeParticipant",
+        );
+      }
+      // Status / Stories
+      if (gate("status")) {
+        result.push("send-status", "delete-status");
+      }
+      // WhatsApp Channels (newsletters)
+      if (gate("waChannels")) {
+        result.push(
+          "list-wa-channels",
+          "get-wa-channel",
+          "create-wa-channel",
+          "delete-wa-channel",
+          "get-wa-channel-messages",
+        );
+      }
+      return result;
+    },
+
+    supportsAction: ({ action }) => (ALL_ACTIONS as readonly string[]).includes(action),
+
+    handleAction: async ({ action, params, cfg, accountId }) => {
+      const p = params as Record<string, unknown>;
+      const account = resolveWahaV2Account(cfg, accountId);
+      const client = getWahaV2Client(account.accountId);
+      if (!client) {
+        throw new Error(`waha-v2: no active client for account "${account.accountId}"`);
+      }
+      const session = account.session;
+
+      // -----------------------------------------------------------------------
+      // Session management
+      // -----------------------------------------------------------------------
+
+      if (action === "start-session") {
+        acquireLoginLock(account.accountId);
+        try {
+          await client.startSession(session).catch(async () => {
+            await client.createSession(session);
+          });
+          const waitResult = await waitForWahaV2Connected(client, session, 5_000).catch(() => ({
+            ok: false,
+          }));
+          const probe = await probeWahaV2Session(client, session).catch(() => ({ ok: false }));
+          return jsonResult({
+            ok: true,
+            action: "start-session",
+            session,
+            connected: probe.ok,
+            status: (probe as { status?: string }).status ?? null,
+            alreadyConnected: waitResult.ok,
+          });
+        } finally {
+          releaseLoginLock(account.accountId);
+        }
+      }
+
+      if (action === "get-qr") {
+        const qr = await client.getQr(session);
+        if (!qr?.data) {
+          return jsonResult({
+            ok: false,
+            action: "get-qr",
+            error: "QR not available — session may already be connected or not in QR pairing mode",
+          });
+        }
+        return jsonResult({ ok: true, action: "get-qr", session, data: qr.data });
+      }
+
+      if (action === "request-code") {
+        const phoneNumber = String(p.phoneNumber ?? "").trim();
+        if (!phoneNumber) throw new Error("waha-v2: request-code requires params.phoneNumber");
+        acquireLoginLock(account.accountId);
+        try {
+          const prep = await prepareSessionForRequestCode({ client, session });
+          // Give WAHA a short transition window before requesting pairing code.
+          await sleep(5_000);
+          const result = await client.requestCode(session, phoneNumber);
+          return jsonResult({
+            ok: true,
+            action: "request-code",
+            session,
+            sessionExisted: prep.sessionExisted,
+            previousStatus: prep.previousStatus,
+            restarted: prep.restarted,
+            waitedMs: 5_000,
+            code: result?.code ?? null,
+          });
+        } finally {
+          releaseLoginLock(account.accountId);
+        }
+      }
+
+      if (action === "logout-session") {
+        await client.logoutSession(session);
+        return jsonResult({ ok: true, action: "logout-session", session });
+      }
+
+      // -----------------------------------------------------------------------
+      // Message actions
+      // -----------------------------------------------------------------------
+
+      if (action === "react") {
+        const messageId = String(p.messageId ?? "");
+        const emoji = String(p.emoji ?? "");
+        await client.addReaction(session, messageId, emoji);
+        return jsonResult({ ok: true, action: "react", messageId });
+      }
+
+      if (action === "send-seen") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageIds = Array.isArray(p.messageIds) ? (p.messageIds as string[]) : undefined;
+        await client.sendSeen(session, chatId, messageIds);
+        return jsonResult({ ok: true, action: "send-seen", chatId });
+      }
+
+      if (action === "send-location") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const latitude = Number(p.latitude);
+        const longitude = Number(p.longitude);
+        const title = p.title ? String(p.title) : undefined;
+        if (!chatId || isNaN(latitude) || isNaN(longitude)) {
+          throw new Error("waha-v2: send-location requires to, latitude, longitude");
+        }
+        const result = await client.sendLocation(session, chatId, latitude, longitude, title);
+        return jsonResult({ ok: true, action: "send-location", chatId, result });
+      }
+
+      if (action === "send-contact") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const contacts = Array.isArray(p.contacts) ? p.contacts : [p.contact].filter(Boolean);
+        if (!chatId || contacts.length === 0) {
+          throw new Error("waha-v2: send-contact requires to and contacts array");
+        }
+        const result = await client.sendContact(session, chatId, contacts);
+        return jsonResult({ ok: true, action: "send-contact", chatId, result });
+      }
+
+      if (action === "forward-message") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        if (!chatId || !messageId)
+          throw new Error("waha-v2: forward-message requires to and messageId");
+        const result = await client.forwardMessage(session, chatId, messageId);
+        return jsonResult({ ok: true, action: "forward-message", chatId, result });
+      }
+
+      if (action === "star-message") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        await client.starMessage(session, chatId, messageId, true);
+        return jsonResult({ ok: true, action: "star-message", chatId, messageId });
+      }
+
+      if (action === "unstar-message") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        await client.starMessage(session, chatId, messageId, false);
+        return jsonResult({ ok: true, action: "unstar-message", chatId, messageId });
+      }
+
+      if (action === "edit") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        const text = String(p.text ?? "");
+        if (!chatId || !messageId || !text)
+          throw new Error("waha-v2: edit requires to, messageId, text");
+        await client.editMessage(session, chatId, messageId, text);
+        return jsonResult({ ok: true, action: "edit", chatId, messageId });
+      }
+
+      if (action === "delete") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        if (!chatId || !messageId) throw new Error("waha-v2: delete requires to and messageId");
+        await client.deleteMessage(session, chatId, messageId);
+        return jsonResult({ ok: true, action: "delete", chatId, messageId });
+      }
+
+      if (action === "pin") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        if (!chatId || !messageId) throw new Error("waha-v2: pin requires to and messageId");
+        await client.pinMessage(session, chatId, messageId);
+        return jsonResult({ ok: true, action: "pin", chatId, messageId });
+      }
+
+      if (action === "unpin") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        if (!chatId || !messageId) throw new Error("waha-v2: unpin requires to and messageId");
+        await client.unpinMessage(session, chatId, messageId);
+        return jsonResult({ ok: true, action: "unpin", chatId, messageId });
+      }
+
+      // -----------------------------------------------------------------------
+      // Chats
+      // -----------------------------------------------------------------------
+
+      if (action === "list-chats") {
+        const limit = p.limit ? Number(p.limit) : undefined;
+        const offset = p.offset ? Number(p.offset) : undefined;
+        const chats = await client.listChats(session, limit, offset);
+        return jsonResult({ ok: true, action: "list-chats", chats });
+      }
+
+      if (action === "get-chat-messages") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: get-chat-messages requires to");
+        const limit = p.limit ? Number(p.limit) : undefined;
+        const messages = await client.getChatMessages(session, chatId, limit);
+        return jsonResult({ ok: true, action: "get-chat-messages", chatId, messages });
+      }
+
+      if (action === "get-message") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        const messageId = String(p.messageId ?? "");
+        if (!chatId || !messageId)
+          throw new Error("waha-v2: get-message requires to and messageId");
+        const message = await client.getChatMessage(session, chatId, messageId);
+        return jsonResult({ ok: true, action: "get-message", chatId, messageId, message });
+      }
+
+      if (action === "archive-chat") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: archive-chat requires to");
+        await client.archiveChat(session, chatId);
+        return jsonResult({ ok: true, action: "archive-chat", chatId });
+      }
+
+      if (action === "unarchive-chat") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: unarchive-chat requires to");
+        await client.unarchiveChat(session, chatId);
+        return jsonResult({ ok: true, action: "unarchive-chat", chatId });
+      }
+
+      if (action === "delete-chat") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: delete-chat requires to");
+        await client.deleteChat(session, chatId);
+        return jsonResult({ ok: true, action: "delete-chat", chatId });
+      }
+
+      if (action === "mark-chat-unread") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: mark-chat-unread requires to");
+        await client.markChatUnread(session, chatId);
+        return jsonResult({ ok: true, action: "mark-chat-unread", chatId });
+      }
+
+      // -----------------------------------------------------------------------
+      // Contacts
+      // -----------------------------------------------------------------------
+
+      if (action === "list-contacts") {
+        const limit = p.limit ? Number(p.limit) : undefined;
+        const offset = p.offset ? Number(p.offset) : undefined;
+        const contacts = await client.listContacts(session, limit, offset);
+        return jsonResult({ ok: true, action: "list-contacts", contacts });
+      }
+
+      if (action === "get-contact") {
+        const contactId = String(p.contactId ?? p.target ?? p.to ?? "");
+        if (!contactId) throw new Error("waha-v2: get-contact requires contactId");
+        const contact = await client.getContact(session, contactId);
+        return jsonResult({ ok: true, action: "get-contact", contactId, contact });
+      }
+
+      if (action === "check-contact") {
+        const phone = String(p.phone ?? p.phoneNumber ?? "").trim();
+        if (!phone) throw new Error("waha-v2: check-contact requires phone");
+        const result = await client.checkContactExists(session, phone);
+        return jsonResult({ ok: true, action: "check-contact", phone, result });
+      }
+
+      if (action === "block-contact") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: block-contact requires to");
+        await client.blockContact(session, chatId);
+        return jsonResult({ ok: true, action: "block-contact", chatId });
+      }
+
+      if (action === "unblock-contact") {
+        const chatId = String(p.target ?? p.to ?? p.chatId ?? "");
+        if (!chatId) throw new Error("waha-v2: unblock-contact requires to");
+        await client.unblockContact(session, chatId);
+        return jsonResult({ ok: true, action: "unblock-contact", chatId });
+      }
+
+      // -----------------------------------------------------------------------
+      // Groups
+      // -----------------------------------------------------------------------
+
+      if (action === "list-groups") {
+        const groups = await client.listGroups(session);
+        return jsonResult({ ok: true, action: "list-groups", groups });
+      }
+
+      if (action === "get-group") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (!groupId) throw new Error("waha-v2: get-group requires groupId");
+        const group = await client.getGroup(session, groupId);
+        return jsonResult({ ok: true, action: "get-group", groupId, group });
+      }
+
+      if (action === "create-group") {
+        const subject = String(p.subject ?? p.name ?? "");
+        if (!subject) throw new Error("waha-v2: create-group requires subject");
+        const participants = Array.isArray(p.participants) ? (p.participants as string[]) : [];
+        const group = await client.createGroup(session, subject, participants);
+        return jsonResult({ ok: true, action: "create-group", group });
+      }
+
+      if (action === "get-group-participants") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (!groupId) throw new Error("waha-v2: get-group-participants requires groupId");
+        const participants = await client.getGroupParticipants(session, groupId);
+        return jsonResult({ ok: true, action: "get-group-participants", groupId, participants });
+      }
+
+      if (action === "add-group-participants" || action === "addParticipant") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0) {
+          throw new Error("waha-v2: add-group-participants requires groupId and participants");
+        }
+        const result = await client.addGroupParticipants(session, groupId, participants);
+        return jsonResult({ ok: true, action: "add-group-participants", groupId, result });
+      }
+
+      if (action === "remove-group-participants" || action === "removeParticipant") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0) {
+          throw new Error("waha-v2: remove-group-participants requires groupId and participants");
+        }
+        const result = await client.removeGroupParticipants(session, groupId, participants);
+        return jsonResult({ ok: true, action: "remove-group-participants", groupId, result });
+      }
+
+      if (action === "promote-group-admin") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0)
+          throw new Error("waha-v2: promote-group-admin requires groupId and participants");
+        const result = await client.promoteGroupAdmin(session, groupId, participants);
+        return jsonResult({ ok: true, action: "promote-group-admin", groupId, result });
+      }
+
+      if (action === "demote-group-admin") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        const participants = Array.isArray(p.participants)
+          ? (p.participants as string[])
+          : [String(p.participant ?? "")].filter(Boolean);
+        if (!groupId || participants.length === 0)
+          throw new Error("waha-v2: demote-group-admin requires groupId and participants");
+        const result = await client.demoteGroupAdmin(session, groupId, participants);
+        return jsonResult({ ok: true, action: "demote-group-admin", groupId, result });
+      }
+
+      if (action === "get-group-invite-code") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (!groupId) throw new Error("waha-v2: get-group-invite-code requires groupId");
+        const result = await client.getGroupInviteCode(session, groupId);
+        return jsonResult({ ok: true, action: "get-group-invite-code", groupId, result });
+      }
+
+      if (action === "revoke-group-invite-code") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (!groupId) throw new Error("waha-v2: revoke-group-invite-code requires groupId");
+        const result = await client.revokeGroupInviteCode(session, groupId);
+        return jsonResult({ ok: true, action: "revoke-group-invite-code", groupId, result });
+      }
+
+      if (action === "renameGroup" || action === "update-group-description") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (action === "renameGroup") {
+          const subject = String(p.name ?? p.subject ?? "");
+          if (!groupId || !subject)
+            throw new Error("waha-v2: renameGroup requires groupId and name");
+          await client.updateGroupSubject(session, groupId, subject);
+          return jsonResult({ ok: true, action: "renameGroup", groupId });
+        }
+        const description = String(p.description ?? "");
+        if (!groupId || !description)
+          throw new Error("waha-v2: update-group-description requires groupId and description");
+        await client.updateGroupDescription(session, groupId, description);
+        return jsonResult({ ok: true, action: "update-group-description", groupId });
+      }
+
+      if (action === "leaveGroup") {
+        const groupId = String(p.groupId ?? p.target ?? p.to ?? "");
+        if (!groupId) throw new Error("waha-v2: leaveGroup requires groupId");
+        await client.leaveGroup(session, groupId);
+        return jsonResult({ ok: true, action: "leaveGroup", groupId });
+      }
+
+      // -----------------------------------------------------------------------
+      // Status / Stories
+      // -----------------------------------------------------------------------
+
+      if (action === "send-status") {
+        const text = String(p.text ?? "").trim();
+        if (!text) throw new Error("waha-v2: send-status requires text (text status only for now)");
+        const result = await client.sendStatusText(session, text);
+        return jsonResult({ ok: true, action: "send-status", result });
+      }
+
+      if (action === "delete-status") {
+        const messageId = String(p.messageId ?? "");
+        if (!messageId) throw new Error("waha-v2: delete-status requires messageId");
+        await client.deleteStatus(session, messageId);
+        return jsonResult({ ok: true, action: "delete-status", messageId });
+      }
+
+      // -----------------------------------------------------------------------
+      // WhatsApp Channels (Newsletters)
+      // -----------------------------------------------------------------------
+
+      if (action === "list-wa-channels") {
+        const channels = await client.listWaChannels(session);
+        return jsonResult({ ok: true, action: "list-wa-channels", channels });
+      }
+
+      if (action === "get-wa-channel") {
+        const channelId = String(p.channelId ?? "");
+        if (!channelId) throw new Error("waha-v2: get-wa-channel requires channelId");
+        const channel = await client.getWaChannel(session, channelId);
+        return jsonResult({ ok: true, action: "get-wa-channel", channelId, channel });
+      }
+
+      if (action === "create-wa-channel") {
+        const name = String(p.name ?? "");
+        if (!name) throw new Error("waha-v2: create-wa-channel requires name");
+        const description = p.description ? String(p.description) : undefined;
+        const channel = await client.createWaChannel(session, name, description);
+        return jsonResult({ ok: true, action: "create-wa-channel", channel });
+      }
+
+      if (action === "delete-wa-channel") {
+        const channelId = String(p.channelId ?? "");
+        if (!channelId) throw new Error("waha-v2: delete-wa-channel requires channelId");
+        await client.deleteWaChannel(session, channelId);
+        return jsonResult({ ok: true, action: "delete-wa-channel", channelId });
+      }
+
+      if (action === "get-wa-channel-messages") {
+        const channelId = String(p.channelId ?? "");
+        if (!channelId) throw new Error("waha-v2: get-wa-channel-messages requires channelId");
+        const limit = p.limit ? Number(p.limit) : undefined;
+        const messages = await client.getWaChannelMessages(session, channelId, limit);
+        return jsonResult({ ok: true, action: "get-wa-channel-messages", channelId, messages });
+      }
+
+      throw new Error(`waha-v2: action "${action}" is not supported`);
+    },
+  },
+
+  status: {
+    defaultRuntime: {
+      accountId: WAHA_V2_DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastError: null,
+    },
+
+    probeAccount: async ({ account }) => {
+      const client = getWahaV2Client(account.accountId);
+      if (!client) return { ok: false, error: "gateway not running" };
+      return probeWahaV2Session(client, account.session);
+    },
+
+    buildChannelSummary: async ({ account, snapshot }) => ({
+      configured: Boolean(account.baseUrl && account.apiKey),
+      linked: Boolean(account.baseUrl && account.apiKey),
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastError: snapshot.lastError ?? null,
+      transport: "waha-v2",
+      baseUrl: account.baseUrl ?? null,
+      session: account.session ?? "default",
+    }),
+
+    buildAccountSnapshot: async ({ account, runtime, probe }) => {
+      const probeOk = (probe as { ok?: boolean } | undefined)?.ok === true;
+      const probeErr = (probe as { error?: string } | undefined)?.error ?? null;
+      const connected = probeOk || (runtime?.connected ?? false);
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: Boolean(account.baseUrl && account.apiKey),
+        linked: Boolean(account.baseUrl && account.apiKey),
+        running: runtime?.running ?? false,
+        connected,
+        // Clear stale errors once the session is confirmed connected.
+        lastError: connected ? null : (runtime?.lastError ?? probeErr),
+        baseUrl: account.baseUrl,
+        dmPolicy: account.dmPolicy,
+        groupPolicy: account.groupPolicy,
+        allowFrom: account.allowFrom,
+        allowGroups: account.allowGroups,
+        probe,
+      };
+    },
+  },
+
+  outbound: wahaV2Outbound,
+  gateway: wahaV2Gateway,
+};
+
+// ---------------------------------------------------------------------------
+// Config mutation helpers used by setup/config adapters
+// ---------------------------------------------------------------------------
+
+export function _setWahaV2ChannelRootConfig(
+  cfg: OpenClawConfig,
+  patch: Record<string, unknown>,
+): 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;
+}