@openclaw/whatsapp 2026.5.1-beta.1

package/src/accounts.whatsapp-auth.test.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { captureEnv } from "openclaw/plugin-sdk/test-env";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { hasAnyWhatsAppAuth, listWhatsAppAuthDirs } from "./accounts.js";
+
+describe("hasAnyWhatsAppAuth", () => {
+  let envSnapshot: ReturnType<typeof captureEnv>;
+  let tempOauthDir: string | undefined;
+
+  const writeCreds = (dir: string) => {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "creds.json"), JSON.stringify({ me: {} }));
+  };
+
+  beforeEach(() => {
+    envSnapshot = captureEnv(["OPENCLAW_OAUTH_DIR"]);
+    tempOauthDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-oauth-"));
+    process.env.OPENCLAW_OAUTH_DIR = tempOauthDir;
+  });
+
+  afterEach(() => {
+    envSnapshot.restore();
+    if (tempOauthDir) {
+      fs.rmSync(tempOauthDir, { recursive: true, force: true });
+      tempOauthDir = undefined;
+    }
+  });
+
+  it("returns false when no auth exists", () => {
+    expect(hasAnyWhatsAppAuth({})).toBe(false);
+  });
+
+  it("returns true when legacy auth exists", () => {
+    fs.writeFileSync(path.join(tempOauthDir ?? "", "creds.json"), JSON.stringify({ me: {} }));
+    expect(hasAnyWhatsAppAuth({})).toBe(true);
+  });
+
+  it("returns true when non-default auth exists", () => {
+    writeCreds(path.join(tempOauthDir ?? "", "whatsapp", "work"));
+    expect(hasAnyWhatsAppAuth({})).toBe(true);
+  });
+
+  it("includes authDir overrides", () => {
+    const customDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-wa-auth-"));
+    try {
+      writeCreds(customDir);
+      const cfg = {
+        channels: { whatsapp: { accounts: { work: { authDir: customDir } } } },
+      };
+
+      expect(listWhatsAppAuthDirs(cfg)).toContain(customDir);
+      expect(hasAnyWhatsAppAuth(cfg)).toBe(true);
+    } finally {
+      fs.rmSync(customDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/action-runtime-target-auth.ts

@@ -0,0 +1,27 @@
+import { ToolAuthorizationError } from "openclaw/plugin-sdk/channel-actions";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveWhatsAppAccount } from "./accounts.js";
+import { resolveWhatsAppOutboundTarget } from "./resolve-outbound-target.js";
+
+export function resolveAuthorizedWhatsAppOutboundTarget(params: {
+  cfg: OpenClawConfig;
+  chatJid: string;
+  accountId?: string;
+  actionLabel: string;
+}): { to: string; accountId: string } {
+  const account = resolveWhatsAppAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const resolution = resolveWhatsAppOutboundTarget({
+    to: params.chatJid,
+    allowFrom: account.allowFrom ?? [],
+    mode: "implicit",
+  });
+  if (!resolution.ok) {
+    throw new ToolAuthorizationError(
+      `WhatsApp ${params.actionLabel} blocked: chatJid "${params.chatJid}" is not in the configured allowFrom list for account "${account.accountId}".`,
+    );
+  }
+  return { to: resolution.to, accountId: account.accountId };
+}

package/src/action-runtime.test.ts

@@ -0,0 +1,330 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/routing";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { handleWhatsAppAction, whatsAppActionRuntime } from "./action-runtime.js";
+
+const originalWhatsAppActionRuntime = { ...whatsAppActionRuntime };
+const sendReactionWhatsApp = vi.fn(async () => undefined);
+
+const enabledConfig = {
+  channels: { whatsapp: { actions: { reactions: true } } },
+} as OpenClawConfig;
+
+describe("handleWhatsAppAction", () => {
+  function reactionConfig(reactionLevel: "minimal" | "extensive" | "off" | "ack"): OpenClawConfig {
+    return {
+      channels: { whatsapp: { actions: { reactions: true }, reactionLevel } },
+    } as OpenClawConfig;
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    Object.assign(whatsAppActionRuntime, originalWhatsAppActionRuntime, {
+      sendReactionWhatsApp,
+    });
+  });
+
+  it("adds reactions", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "✅",
+      },
+      enabledConfig,
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "✅",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("adds reactions when reactionLevel is minimal", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "✅",
+      },
+      reactionConfig("minimal"),
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "✅",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("adds reactions when reactionLevel is extensive", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "✅",
+      },
+      reactionConfig("extensive"),
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "✅",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("removes reactions on empty emoji", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "",
+      },
+      enabledConfig,
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("removes reactions when remove flag set", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "✅",
+        remove: true,
+      },
+      enabledConfig,
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("passes account scope and sender flags", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "🎉",
+        accountId: "work",
+        fromMe: true,
+        participant: "999@s.whatsapp.net",
+      },
+      enabledConfig,
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "🎉",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: true,
+        participant: "999@s.whatsapp.net",
+        accountId: "work",
+      }),
+    );
+  });
+
+  it("preserves LID participant ids when forwarding reactions", async () => {
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "12345@g.us",
+        messageId: "msg1",
+        emoji: "🎉",
+        participant: "123@lid",
+      },
+      enabledConfig,
+    );
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "12345@g.us",
+      "msg1",
+      "🎉",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: "123@lid",
+        accountId: DEFAULT_ACCOUNT_ID,
+      }),
+    );
+  });
+
+  it("respects reaction gating", async () => {
+    const cfg = {
+      channels: { whatsapp: { actions: { reactions: false } } },
+    } as OpenClawConfig;
+    await expect(
+      handleWhatsAppAction(
+        {
+          action: "react",
+          chatJid: "123@s.whatsapp.net",
+          messageId: "msg1",
+          emoji: "✅",
+        },
+        cfg,
+      ),
+    ).rejects.toThrow(/WhatsApp reactions are disabled/);
+  });
+
+  it("disables reactions when WhatsApp is not configured", async () => {
+    await expect(
+      handleWhatsAppAction(
+        {
+          action: "react",
+          chatJid: "123@s.whatsapp.net",
+          messageId: "msg1",
+          emoji: "✅",
+        },
+        {} as OpenClawConfig,
+      ),
+    ).rejects.toThrow(/WhatsApp reactions are disabled/);
+  });
+
+  it("prefers the action gate error when both actions.reactions and reactionLevel disable reactions", async () => {
+    const cfg = {
+      channels: { whatsapp: { actions: { reactions: false }, reactionLevel: "ack" } },
+    } as OpenClawConfig;
+
+    await expect(
+      handleWhatsAppAction(
+        {
+          action: "react",
+          chatJid: "123@s.whatsapp.net",
+          messageId: "msg1",
+          emoji: "✅",
+        },
+        cfg,
+      ),
+    ).rejects.toThrow(/WhatsApp reactions are disabled/);
+    expect(sendReactionWhatsApp).not.toHaveBeenCalled();
+  });
+
+  it.each(["off", "ack"] as const)(
+    "blocks agent reactions when reactionLevel is %s",
+    async (reactionLevel) => {
+      await expect(
+        handleWhatsAppAction(
+          {
+            action: "react",
+            chatJid: "123@s.whatsapp.net",
+            messageId: "msg1",
+            emoji: "✅",
+          },
+          reactionConfig(reactionLevel),
+        ),
+      ).rejects.toThrow(
+        new RegExp(`WhatsApp agent reactions disabled \\(reactionLevel="${reactionLevel}"\\)`),
+      );
+      expect(sendReactionWhatsApp).not.toHaveBeenCalled();
+    },
+  );
+
+  it("applies default account allowFrom when accountId is omitted", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          actions: { reactions: true },
+          allowFrom: ["111@s.whatsapp.net"],
+          accounts: {
+            [DEFAULT_ACCOUNT_ID]: {
+              allowFrom: ["222@s.whatsapp.net"],
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      handleWhatsAppAction(
+        {
+          action: "react",
+          chatJid: "111@s.whatsapp.net",
+          messageId: "msg1",
+          emoji: "✅",
+        },
+        cfg,
+      ),
+    ).rejects.toMatchObject({
+      name: "ToolAuthorizationError",
+      status: 403,
+    });
+  });
+
+  it("routes to resolved default account when no accountId is provided", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          actions: { reactions: true },
+          accounts: {
+            work: {
+              allowFrom: ["123@s.whatsapp.net"],
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await handleWhatsAppAction(
+      {
+        action: "react",
+        chatJid: "123@s.whatsapp.net",
+        messageId: "msg1",
+        emoji: "✅",
+      },
+      cfg,
+    );
+
+    expect(sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "+123",
+      "msg1",
+      "✅",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: undefined,
+        participant: undefined,
+        accountId: "work",
+      }),
+    );
+  });
+});

package/src/action-runtime.ts

@@ -0,0 +1,76 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import {
+  createActionGate,
+  jsonResult,
+  readReactionParams,
+  readStringParam,
+} from "openclaw/plugin-sdk/channel-actions";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveAuthorizedWhatsAppOutboundTarget } from "./action-runtime-target-auth.js";
+import { resolveWhatsAppReactionLevel } from "./reaction-level.js";
+import { sendReactionWhatsApp } from "./send.js";
+
+export const whatsAppActionRuntime = {
+  resolveAuthorizedWhatsAppOutboundTarget,
+  sendReactionWhatsApp,
+};
+
+export async function handleWhatsAppAction(
+  params: Record<string, unknown>,
+  cfg: OpenClawConfig,
+): Promise<AgentToolResult<unknown>> {
+  const action = readStringParam(params, "action", { required: true });
+  const whatsAppConfig = cfg.channels?.whatsapp;
+  const isActionEnabled = createActionGate(whatsAppConfig?.actions);
+
+  if (action === "react") {
+    const accountId = readStringParam(params, "accountId");
+    if (!whatsAppConfig) {
+      throw new Error("WhatsApp reactions are disabled.");
+    }
+    if (!isActionEnabled("reactions")) {
+      throw new Error("WhatsApp reactions are disabled.");
+    }
+    const reactionLevelInfo = resolveWhatsAppReactionLevel({
+      cfg,
+      accountId: accountId ?? undefined,
+    });
+    if (!reactionLevelInfo.agentReactionsEnabled) {
+      throw new Error(
+        `WhatsApp agent reactions disabled (reactionLevel="${reactionLevelInfo.level}"). ` +
+          `Set channels.whatsapp.reactionLevel to "minimal" or "extensive" to enable.`,
+      );
+    }
+    const chatJid = readStringParam(params, "chatJid", { required: true });
+    const messageId = readStringParam(params, "messageId", { required: true });
+    const { emoji, remove, isEmpty } = readReactionParams(params, {
+      removeErrorMessage: "Emoji is required to remove a WhatsApp reaction.",
+    });
+    const participant = readStringParam(params, "participant");
+    const fromMeRaw = params.fromMe;
+    const fromMe = typeof fromMeRaw === "boolean" ? fromMeRaw : undefined;
+
+    // Resolve account + allowFrom via shared account logic so auth and routing stay aligned.
+    const resolved = whatsAppActionRuntime.resolveAuthorizedWhatsAppOutboundTarget({
+      cfg,
+      chatJid,
+      accountId,
+      actionLabel: "reaction",
+    });
+
+    const resolvedEmoji = remove ? "" : emoji;
+    await whatsAppActionRuntime.sendReactionWhatsApp(resolved.to, messageId, resolvedEmoji, {
+      verbose: false,
+      fromMe,
+      participant: participant ?? undefined,
+      accountId: resolved.accountId,
+      cfg,
+    });
+    if (!remove && !isEmpty) {
+      return jsonResult({ ok: true, added: emoji });
+    }
+    return jsonResult({ ok: true, removed: true });
+  }
+
+  throw new Error(`Unsupported WhatsApp action: ${action}`);
+}

package/src/active-listener.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getActiveWebListener, resolveWebAccountId } from "./active-listener.js";
+
+const registryMocks = vi.hoisted(() => ({
+  getRegisteredWhatsAppConnectionController: vi.fn(),
+}));
+
+vi.mock("./connection-controller-registry.js", () => ({
+  getRegisteredWhatsAppConnectionController:
+    registryMocks.getRegisteredWhatsAppConnectionController,
+}));
+
+const WHATSAPP_ACTIVE_LISTENER_TEST_CFG = {
+  channels: { whatsapp: { accounts: { work: { enabled: true } }, defaultAccount: "work" } },
+};
+
+function makeListener() {
+  return {
+    sendMessage: vi.fn(async () => ({ messageId: "msg-1" })),
+    sendPoll: vi.fn(async () => ({ messageId: "poll-1" })),
+    sendReaction: vi.fn(async () => {}),
+    sendComposingTo: vi.fn(async () => {}),
+  };
+}
+
+beforeEach(() => {
+  registryMocks.getRegisteredWhatsAppConnectionController.mockReset();
+});
+
+describe("active WhatsApp listener view", () => {
+  it("reads controller-backed state", () => {
+    const listener = makeListener();
+    registryMocks.getRegisteredWhatsAppConnectionController.mockImplementation(
+      (accountId: string) =>
+        accountId === "work"
+          ? {
+              getActiveListener: () => listener,
+            }
+          : null,
+    );
+
+    expect(getActiveWebListener("work")).toBe(listener);
+  });
+
+  it("resolves the configured default account when accountId is omitted", () => {
+    const listener = makeListener();
+    registryMocks.getRegisteredWhatsAppConnectionController.mockImplementation(
+      (accountId: string) =>
+        accountId === "work"
+          ? {
+              getActiveListener: () => listener,
+            }
+          : null,
+    );
+
+    expect(resolveWebAccountId({ cfg: WHATSAPP_ACTIVE_LISTENER_TEST_CFG })).toBe("work");
+    expect(getActiveWebListener("work")).toBe(listener);
+  });
+
+  it("returns null when the controller has no active listener for the account", () => {
+    registryMocks.getRegisteredWhatsAppConnectionController.mockReturnValue(null);
+
+    expect(getActiveWebListener("work")).toBeNull();
+  });
+});

package/src/active-listener.ts

@@ -0,0 +1,17 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveDefaultWhatsAppAccountId } from "./account-ids.js";
+import { getRegisteredWhatsAppConnectionController } from "./connection-controller-registry.js";
+import type { ActiveWebListener, ActiveWebSendOptions } from "./inbound/types.js";
+
+export type { ActiveWebListener, ActiveWebSendOptions } from "./inbound/types.js";
+
+export function resolveWebAccountId(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): string {
+  return (params.accountId ?? "").trim() || resolveDefaultWhatsAppAccountId(params.cfg);
+}
+
+export function getActiveWebListener(accountId: string): ActiveWebListener | null {
+  return getRegisteredWhatsAppConnectionController(accountId)?.getActiveListener() ?? null;
+}

package/src/agent-tools-login.test.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { startWebLoginWithQr, waitForWebLogin } from "../login-qr-api.js";
+import { createWhatsAppLoginTool } from "./agent-tools-login.js";
+
+vi.mock("../login-qr-api.js", () => ({
+  startWebLoginWithQr: vi.fn(),
+  waitForWebLogin: vi.fn(),
+}));
+
+const startWebLoginWithQrMock = vi.mocked(startWebLoginWithQr);
+const waitForWebLoginMock = vi.mocked(waitForWebLogin);
+
+describe("createWhatsAppLoginTool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("passes the caller's current QR back into wait actions", async () => {
+    const accountId = "account-1";
+    waitForWebLoginMock.mockResolvedValueOnce({
+      connected: false,
+      message: "QR refreshed. Scan the latest code in WhatsApp → Linked Devices.",
+      qrDataUrl: "data:image/png;base64,next-qr",
+    });
+
+    const tool = createWhatsAppLoginTool();
+    const result = await tool.execute("tool-call-1", {
+      action: "wait",
+      timeoutMs: 5000,
+      accountId,
+      currentQrDataUrl: "data:image/png;base64,current-qr",
+    });
+
+    expect(waitForWebLoginMock).toHaveBeenCalledWith({
+      accountId,
+      timeoutMs: 5000,
+      currentQrDataUrl: "data:image/png;base64,current-qr",
+    });
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: [
+            "QR refreshed. Scan the latest code in WhatsApp → Linked Devices.",
+            "",
+            "Open WhatsApp → Linked Devices and scan:",
+            "",
+            "![whatsapp-qr](data:image/png;base64,next-qr)",
+          ].join("\n"),
+        },
+      ],
+      details: {
+        connected: false,
+        qr: true,
+      },
+    });
+  });
+
+  it("does not retain QR state across tool actions", async () => {
+    const accountId = "account-2";
+    startWebLoginWithQrMock.mockResolvedValueOnce({
+      connected: false,
+      message: "Scan this QR in WhatsApp → Linked Devices.",
+      qrDataUrl: "data:image/png;base64,current-qr",
+    });
+    waitForWebLoginMock.mockResolvedValueOnce({
+      connected: true,
+      message: "✅ Linked! WhatsApp is ready.",
+    });
+
+    const tool = createWhatsAppLoginTool();
+    await tool.execute("tool-call-start", { action: "start", accountId });
+    await tool.execute("tool-call-wait", { action: "wait", timeoutMs: 5000, accountId });
+
+    expect(waitForWebLoginMock).toHaveBeenCalledWith({
+      accountId,
+      timeoutMs: 5000,
+      currentQrDataUrl: undefined,
+    });
+  });
+});