@openclaw/whatsapp 2026.5.1-beta.1

package/src/auto-reply.web-auto-reply.last-route.test.ts

@@ -0,0 +1,184 @@
+import "./test-helpers.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createAcceptedWhatsAppSendResult,
+  installWebAutoReplyUnitTestHooks,
+  makeSessionStore,
+} from "./auto-reply.test-harness.js";
+
+const updateLastRouteInBackgroundMock = vi.hoisted(() => vi.fn());
+let awaitBackgroundTasks: typeof import("./auto-reply/monitor/last-route.js").awaitBackgroundTasks;
+let buildMentionConfig: typeof import("./auto-reply/mentions.js").buildMentionConfig;
+let createEchoTracker: typeof import("./auto-reply/monitor/echo.js").createEchoTracker;
+let createWebOnMessageHandler: typeof import("./auto-reply/monitor/on-message.js").createWebOnMessageHandler;
+
+vi.mock("./auto-reply/monitor/last-route.js", async () => {
+  const actual = await vi.importActual<typeof import("./auto-reply/monitor/last-route.js")>(
+    "./auto-reply/monitor/last-route.js",
+  );
+  return {
+    ...actual,
+    updateLastRouteInBackground: (...args: unknown[]) => updateLastRouteInBackgroundMock(...args),
+  };
+});
+
+function makeCfg(storePath: string): OpenClawConfig {
+  return {
+    channels: { whatsapp: { allowFrom: ["*"] } },
+    session: { store: storePath },
+  };
+}
+
+function makeReplyLogger() {
+  return {
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    error: vi.fn(),
+  } as unknown as Parameters<typeof createWebOnMessageHandler>[0]["replyLogger"];
+}
+
+function createHandlerForTest(opts: { cfg: OpenClawConfig; replyResolver: unknown }) {
+  const backgroundTasks = new Set<Promise<unknown>>();
+  const handler = createWebOnMessageHandler({
+    cfg: opts.cfg,
+    verbose: false,
+    connectionId: "test",
+    maxMediaBytes: 1024,
+    groupHistoryLimit: 3,
+    groupHistories: new Map(),
+    groupMemberNames: new Map(),
+    echoTracker: createEchoTracker({ maxItems: 10 }),
+    backgroundTasks,
+    replyResolver: opts.replyResolver as Parameters<
+      typeof createWebOnMessageHandler
+    >[0]["replyResolver"],
+    replyLogger: makeReplyLogger(),
+    baseMentionConfig: buildMentionConfig(opts.cfg),
+    account: {},
+  });
+
+  return { handler, backgroundTasks };
+}
+
+function createLastRouteHarness(storePath: string) {
+  const replyResolver = vi.fn().mockResolvedValue(undefined);
+  const cfg = makeCfg(storePath);
+  return createHandlerForTest({ cfg, replyResolver });
+}
+
+function buildInboundMessage(params: {
+  id: string;
+  from: string;
+  conversationId: string;
+  chatType: "direct" | "group";
+  chatId: string;
+  timestamp: number;
+  body?: string;
+  to?: string;
+  accountId?: string;
+  senderE164?: string;
+  senderName?: string;
+  selfE164?: string;
+}) {
+  return {
+    id: params.id,
+    from: params.from,
+    conversationId: params.conversationId,
+    to: params.to ?? "+2000",
+    body: params.body ?? "hello",
+    timestamp: params.timestamp,
+    chatType: params.chatType,
+    chatId: params.chatId,
+    accountId: params.accountId ?? "default",
+    senderE164: params.senderE164,
+    senderName: params.senderName,
+    selfE164: params.selfE164,
+    sendComposing: vi.fn().mockResolvedValue(undefined),
+    reply: vi.fn().mockResolvedValue(createAcceptedWhatsAppSendResult("text", "r1")),
+    sendMedia: vi.fn().mockResolvedValue(createAcceptedWhatsAppSendResult("media", "m1")),
+  };
+}
+
+describe("web auto-reply last-route", () => {
+  installWebAutoReplyUnitTestHooks();
+
+  beforeEach(async () => {
+    vi.resetModules();
+    updateLastRouteInBackgroundMock.mockClear();
+    ({ awaitBackgroundTasks } = await import("./auto-reply/monitor/last-route.js"));
+    ({ buildMentionConfig } = await import("./auto-reply/mentions.js"));
+    ({ createEchoTracker } = await import("./auto-reply/monitor/echo.js"));
+    ({ createWebOnMessageHandler } = await import("./auto-reply/monitor/on-message.js"));
+  });
+
+  it("updates last-route for direct chats without senderE164", async () => {
+    const now = Date.now();
+    const mainSessionKey = "agent:main:main";
+    const store = await makeSessionStore({
+      [mainSessionKey]: { sessionId: "sid", updatedAt: now - 1 },
+    });
+
+    const { handler, backgroundTasks } = createLastRouteHarness(store.storePath);
+
+    await handler(
+      buildInboundMessage({
+        id: "m1",
+        from: "+1000",
+        conversationId: "+1000",
+        chatType: "direct",
+        chatId: "direct:+1000",
+        timestamp: now,
+      }),
+    );
+
+    await awaitBackgroundTasks(backgroundTasks);
+
+    expect(updateLastRouteInBackgroundMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "whatsapp",
+        to: "+1000",
+      }),
+    );
+
+    await store.cleanup();
+  });
+
+  it("updates last-route for group chats with account id", async () => {
+    const now = Date.now();
+    const groupSessionKey = "agent:main:whatsapp:group:123@g.us";
+    const store = await makeSessionStore({
+      [groupSessionKey]: { sessionId: "sid", updatedAt: now - 1 },
+    });
+
+    const { handler, backgroundTasks } = createLastRouteHarness(store.storePath);
+
+    await handler(
+      buildInboundMessage({
+        id: "g1",
+        from: "123@g.us",
+        conversationId: "123@g.us",
+        chatType: "group",
+        chatId: "123@g.us",
+        timestamp: now,
+        accountId: "work",
+        senderE164: "+1000",
+        senderName: "Alice",
+        selfE164: "+2000",
+      }),
+    );
+
+    await awaitBackgroundTasks(backgroundTasks);
+
+    expect(updateLastRouteInBackgroundMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "whatsapp",
+        to: "123@g.us",
+        accountId: "work",
+      }),
+    );
+
+    await store.cleanup();
+  });
+});

package/src/channel-actions.runtime.ts

@@ -0,0 +1,7 @@
+import { createActionGate } from "openclaw/plugin-sdk/channel-actions";
+import type { ChannelMessageActionName } from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export { listWhatsAppAccountIds, resolveWhatsAppAccount } from "./accounts.js";
+export { resolveWhatsAppReactionLevel } from "./reaction-level.js";
+export { createActionGate, type ChannelMessageActionName, type OpenClawConfig };

package/src/channel-actions.test.ts

@@ -0,0 +1,216 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  describeWhatsAppMessageActions,
+  resolveWhatsAppAgentReactionGuidance,
+} from "./channel-actions.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+
+const hoisted = vi.hoisted(() => ({
+  listWhatsAppAccountIds: vi.fn((cfg: OpenClawConfig) => {
+    const accountIds = Object.keys(cfg.channels?.whatsapp?.accounts ?? {});
+    return accountIds.length > 0 ? accountIds : ["default"];
+  }),
+  resolveWhatsAppAccount: vi.fn(
+    ({ cfg, accountId }: { cfg: OpenClawConfig; accountId?: string | null }) => ({
+      enabled:
+        accountId == null ? true : cfg.channels?.whatsapp?.accounts?.[accountId]?.enabled !== false,
+    }),
+  ),
+}));
+
+vi.mock("./channel-actions.runtime.js", async () => {
+  return {
+    listWhatsAppAccountIds: hoisted.listWhatsAppAccountIds,
+    resolveWhatsAppAccount: hoisted.resolveWhatsAppAccount,
+    createActionGate: (actions?: { reactions?: boolean; polls?: boolean }) => (name: string) => {
+      if (name === "reactions") {
+        return actions?.reactions !== false;
+      }
+      if (name === "polls") {
+        return actions?.polls !== false;
+      }
+      return true;
+    },
+    resolveWhatsAppReactionLevel: ({
+      cfg,
+      accountId,
+    }: {
+      cfg: OpenClawConfig;
+      accountId?: string;
+    }) => {
+      const accountLevel =
+        accountId == null
+          ? undefined
+          : cfg.channels?.whatsapp?.accounts?.[accountId]?.reactionLevel;
+      const level = accountLevel ?? cfg.channels?.whatsapp?.reactionLevel ?? "minimal";
+      return {
+        level,
+        agentReactionsEnabled: level === "minimal" || level === "extensive",
+        agentReactionGuidance: level === "minimal" || level === "extensive" ? level : undefined,
+      };
+    },
+  };
+});
+
+describe("whatsapp channel action helpers", () => {
+  beforeEach(() => {
+    hoisted.listWhatsAppAccountIds.mockClear();
+    hoisted.resolveWhatsAppAccount.mockClear();
+  });
+
+  it("defaults to minimal reaction guidance when reactions are available", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(resolveWhatsAppAgentReactionGuidance({ cfg, accountId: "default" })).toBe("minimal");
+  });
+
+  it("omits reaction guidance when WhatsApp is not configured", () => {
+    expect(
+      resolveWhatsAppAgentReactionGuidance({
+        cfg: {} as OpenClawConfig,
+        accountId: "default",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns minimal reaction guidance when configured", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "minimal",
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(resolveWhatsAppAgentReactionGuidance({ cfg, accountId: "default" })).toBe("minimal");
+  });
+
+  it("omits reaction guidance when WhatsApp reactions are disabled", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          actions: { reactions: false },
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(resolveWhatsAppAgentReactionGuidance({ cfg, accountId: "default" })).toBeUndefined();
+  });
+
+  it("omits reaction guidance when reactionLevel disables agent reactions", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "ack",
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(resolveWhatsAppAgentReactionGuidance({ cfg, accountId: "default" })).toBeUndefined();
+  });
+
+  it("advertises react when agent reactions are enabled", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(describeWhatsAppMessageActions({ cfg, accountId: "default" })?.actions).toEqual([
+      "react",
+      "poll",
+    ]);
+  });
+
+  it("returns null when WhatsApp is not configured", () => {
+    expect(
+      describeWhatsAppMessageActions({ cfg: {} as OpenClawConfig, accountId: "default" }),
+    ).toBeNull();
+  });
+
+  it("omits react when reactionLevel disables agent reactions", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "ack",
+          allowFrom: ["*"],
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(describeWhatsAppMessageActions({ cfg, accountId: "default" })?.actions).toEqual([
+      "poll",
+    ]);
+  });
+
+  it("uses the active account reactionLevel for discovery", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "ack",
+          allowFrom: ["*"],
+          accounts: {
+            work: {
+              reactionLevel: "minimal",
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(describeWhatsAppMessageActions({ cfg, accountId: "work" })?.actions).toEqual([
+      "react",
+      "poll",
+    ]);
+  });
+
+  it("keeps react in global discovery when any account enables agent reactions", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "ack",
+          allowFrom: ["*"],
+          accounts: {
+            work: {
+              reactionLevel: "minimal",
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+    hoisted.listWhatsAppAccountIds.mockReturnValue(["default", "work"]);
+
+    expect(describeWhatsAppMessageActions({ cfg })?.actions).toEqual(["react", "poll"]);
+  });
+
+  it("omits react in global discovery when only disabled accounts enable agent reactions", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "ack",
+          allowFrom: ["*"],
+          accounts: {
+            work: {
+              enabled: false,
+              reactionLevel: "minimal",
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+    hoisted.listWhatsAppAccountIds.mockReturnValue(["default", "work"]);
+
+    expect(describeWhatsAppMessageActions({ cfg })?.actions).toEqual(["poll"]);
+  });
+});

package/src/channel-actions.ts

@@ -0,0 +1,84 @@
+import {
+  listWhatsAppAccountIds,
+  resolveWhatsAppAccount,
+  createActionGate,
+  type ChannelMessageActionName,
+  type OpenClawConfig,
+  resolveWhatsAppReactionLevel,
+} from "./channel-actions.runtime.js";
+
+function areWhatsAppAgentReactionsEnabled(params: { cfg: OpenClawConfig; accountId?: string }) {
+  if (!params.cfg.channels?.whatsapp) {
+    return false;
+  }
+  const gate = createActionGate(params.cfg.channels.whatsapp.actions);
+  if (!gate("reactions")) {
+    return false;
+  }
+  return resolveWhatsAppReactionLevel({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  }).agentReactionsEnabled;
+}
+
+function hasAnyWhatsAppAccountWithAgentReactionsEnabled(cfg: OpenClawConfig) {
+  if (!cfg.channels?.whatsapp) {
+    return false;
+  }
+  return listWhatsAppAccountIds(cfg).some((accountId) => {
+    const account = resolveWhatsAppAccount({ cfg, accountId });
+    if (!account.enabled) {
+      return false;
+    }
+    return areWhatsAppAgentReactionsEnabled({
+      cfg,
+      accountId,
+    });
+  });
+}
+
+export function resolveWhatsAppAgentReactionGuidance(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}) {
+  if (!params.cfg.channels?.whatsapp) {
+    return undefined;
+  }
+  const gate = createActionGate(params.cfg.channels.whatsapp.actions);
+  if (!gate("reactions")) {
+    return undefined;
+  }
+  const resolved = resolveWhatsAppReactionLevel({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (!resolved.agentReactionsEnabled) {
+    return undefined;
+  }
+  return resolved.agentReactionGuidance;
+}
+
+export function describeWhatsAppMessageActions(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): { actions: ChannelMessageActionName[] } | null {
+  if (!params.cfg.channels?.whatsapp) {
+    return null;
+  }
+  const gate = createActionGate(params.cfg.channels.whatsapp.actions);
+  const actions = new Set<ChannelMessageActionName>();
+  const canReact =
+    params.accountId != null
+      ? areWhatsAppAgentReactionsEnabled({
+          cfg: params.cfg,
+          accountId: params.accountId ?? undefined,
+        })
+      : hasAnyWhatsAppAccountWithAgentReactionsEnabled(params.cfg);
+  if (canReact) {
+    actions.add("react");
+  }
+  if (gate("polls")) {
+    actions.add("poll");
+  }
+  return { actions: Array.from(actions) };
+}

package/src/channel-outbound.test.ts

@@ -0,0 +1,131 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const hoisted = vi.hoisted(() => ({
+  sendMessageWhatsApp: vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })),
+  sendPollWhatsApp: vi.fn(async () => ({ messageId: "poll-1", toJid: "jid" })),
+}));
+
+vi.mock("./send.js", () => ({
+  sendMessageWhatsApp: hoisted.sendMessageWhatsApp,
+  sendPollWhatsApp: hoisted.sendPollWhatsApp,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getWhatsAppRuntime: () => ({
+    logging: {
+      shouldLogVerbose: () => false,
+    },
+  }),
+}));
+
+let whatsappChannelOutbound: typeof import("./channel-outbound.js").whatsappChannelOutbound;
+
+describe("whatsappChannelOutbound", () => {
+  beforeAll(async () => {
+    ({ whatsappChannelOutbound } = await import("./channel-outbound.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("drops leading blank lines but preserves intentional indentation", () => {
+    expect(
+      whatsappChannelOutbound.normalizePayload?.({
+        payload: { text: "\n \n    indented" },
+      }),
+    ).toEqual({
+      text: "    indented",
+    });
+  });
+
+  it("keeps XML sanitizer normalization idempotent", () => {
+    const raw = [
+      "<function_calls>",
+      '  <invoke name="send_message">',
+      '    <parameter name="text">hidden</parameter>',
+      "  </invoke>",
+      "</function_calls>",
+      "After",
+    ].join("\n");
+    const once = whatsappChannelOutbound.normalizePayload?.({ payload: { text: raw } });
+    const twice = whatsappChannelOutbound.normalizePayload?.({ payload: { text: once?.text } });
+
+    expect(once?.text).toBe("After");
+    expect(twice?.text).toBe("After");
+  });
+
+  it("drops whitespace-only text after XML sanitizer removal", () => {
+    const raw = [
+      "  <function_calls>",
+      '    <invoke name="send_message">',
+      '      <parameter name="text">hidden</parameter>',
+      "    </invoke>",
+      "  </function_calls>",
+    ].join("\n");
+
+    expect(whatsappChannelOutbound.normalizePayload?.({ payload: { text: raw } })).toEqual({
+      text: "",
+    });
+  });
+
+  it("sanitizes XML tool payloads before plain HTML stripping", () => {
+    const raw = [
+      "Before",
+      "<function_calls>",
+      '  <invoke name="send_message">',
+      '    <parameter name="text">hidden</parameter>',
+      "  </invoke>",
+      "</function_calls>",
+      "After",
+    ].join("\n");
+
+    expect(whatsappChannelOutbound.sanitizeText?.({ text: raw, payload: { text: raw } })).toBe(
+      "Before\n\nAfter",
+    );
+  });
+
+  it("preserves indentation for live text sends", async () => {
+    await whatsappChannelOutbound.sendText!({
+      cfg: {},
+      to: "5511999999999@c.us",
+      text: "\n \n    indented",
+    });
+
+    expect(hoisted.sendMessageWhatsApp).toHaveBeenCalledWith("5511999999999@c.us", "    indented", {
+      verbose: false,
+      cfg: {},
+      accountId: undefined,
+      gifPlayback: undefined,
+      preserveLeadingWhitespace: true,
+    });
+  });
+
+  it("rejects non-WhatsApp provider-prefixed outbound targets", () => {
+    const result = whatsappChannelOutbound.resolveTarget?.({
+      to: "telegram:1234567890",
+      allowFrom: [],
+      mode: undefined,
+    });
+
+    expect(result?.ok).toBe(false);
+    expect(hoisted.sendMessageWhatsApp).not.toHaveBeenCalled();
+  });
+
+  it("preserves indentation for payload delivery", async () => {
+    await whatsappChannelOutbound.sendPayload!({
+      cfg: {},
+      to: "5511999999999@c.us",
+      text: "",
+      payload: { text: "\n \n    indented" },
+    });
+
+    expect(hoisted.sendMessageWhatsApp).toHaveBeenCalledWith("5511999999999@c.us", "    indented", {
+      verbose: false,
+      cfg: {},
+      accountId: undefined,
+      gifPlayback: undefined,
+      preserveLeadingWhitespace: true,
+    });
+  });
+});

package/src/channel-outbound.ts

@@ -0,0 +1,36 @@
+import { chunkText } from "openclaw/plugin-sdk/reply-chunking";
+import { createWhatsAppOutboundBase } from "./outbound-base.js";
+import { normalizeWhatsAppPayloadTextPreservingIndentation } from "./outbound-media-contract.js";
+import { resolveWhatsAppOutboundTarget } from "./resolve-outbound-target.js";
+import { getWhatsAppRuntime } from "./runtime.js";
+import { sendMessageWhatsApp, sendPollWhatsApp } from "./send.js";
+
+export function normalizeWhatsAppChannelPayloadText(text: string | undefined): string {
+  return normalizeWhatsAppPayloadTextPreservingIndentation(text);
+}
+
+function normalizeWhatsAppChannelSendText(text: string | undefined): string {
+  const normalized = normalizeWhatsAppChannelPayloadText(text);
+  return normalized.trim() ? normalized : "";
+}
+
+export const whatsappChannelOutbound = {
+  ...createWhatsAppOutboundBase({
+    chunker: chunkText,
+    sendMessageWhatsApp: async (to, text, options) =>
+      await sendMessageWhatsApp(to, text, {
+        ...options,
+        preserveLeadingWhitespace: true,
+      }),
+    sendPollWhatsApp,
+    shouldLogVerbose: () => getWhatsAppRuntime().logging.shouldLogVerbose(),
+    resolveTarget: ({ to, allowFrom, mode }) =>
+      resolveWhatsAppOutboundTarget({ to, allowFrom, mode }),
+    normalizeText: normalizeWhatsAppChannelSendText,
+  }),
+  sendTextOnlyErrorPayloads: true,
+  normalizePayload: ({ payload }: { payload: { text?: string } }) => ({
+    ...payload,
+    text: normalizeWhatsAppChannelPayloadText(payload.text),
+  }),
+};

package/src/channel-react-action.runtime.ts

@@ -0,0 +1,7 @@
+import { readStringOrNumberParam, readStringParam } from "openclaw/plugin-sdk/channel-actions";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export { resolveReactionMessageId } from "openclaw/plugin-sdk/channel-actions";
+export { handleWhatsAppAction } from "./action-runtime.js";
+export { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "./normalize.js";
+export { readStringOrNumberParam, readStringParam, type OpenClawConfig };