@openclaw/whatsapp 2026.5.1-beta.1

package/src/auto-reply/monitor/ack-reaction.ts

@@ -0,0 +1,99 @@
+import {
+  createAckReactionHandle,
+  shouldAckReactionForWhatsApp,
+  type AckReactionHandle,
+} from "openclaw/plugin-sdk/channel-feedback";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { getSenderIdentity } from "../../identity.js";
+import { resolveWhatsAppReactionLevel } from "../../reaction-level.js";
+import { sendReactionWhatsApp } from "../../send.js";
+import { formatError } from "../../session.js";
+import type { WebInboundMsg } from "../types.js";
+import { resolveGroupActivationFor } from "./group-activation.js";
+
+export async function maybeSendAckReaction(params: {
+  cfg: OpenClawConfig;
+  msg: WebInboundMsg;
+  agentId: string;
+  sessionKey: string;
+  conversationId: string;
+  verbose: boolean;
+  accountId?: string;
+  info: (obj: unknown, msg: string) => void;
+  warn: (obj: unknown, msg: string) => void;
+}): Promise<AckReactionHandle | null> {
+  if (!params.msg.id) {
+    return null;
+  }
+
+  // Keep ackReaction as the emoji/scope control, while letting reactionLevel
+  // suppress all automatic reactions when it is explicitly set to "off".
+  const reactionLevel = resolveWhatsAppReactionLevel({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (reactionLevel.level === "off") {
+    return null;
+  }
+
+  const ackConfig = params.cfg.channels?.whatsapp?.ackReaction;
+  const emoji = (ackConfig?.emoji ?? "").trim();
+  const directEnabled = ackConfig?.direct ?? true;
+  const groupMode = ackConfig?.group ?? "mentions";
+  const conversationIdForCheck = params.msg.conversationId ?? params.msg.from;
+
+  const activation =
+    params.msg.chatType === "group"
+      ? await resolveGroupActivationFor({
+          cfg: params.cfg,
+          accountId: params.accountId,
+          agentId: params.agentId,
+          sessionKey: params.sessionKey,
+          conversationId: conversationIdForCheck,
+        })
+      : null;
+  const shouldSendReaction = () =>
+    shouldAckReactionForWhatsApp({
+      emoji,
+      isDirect: params.msg.chatType === "direct",
+      isGroup: params.msg.chatType === "group",
+      directEnabled,
+      groupMode,
+      wasMentioned: params.msg.wasMentioned === true,
+      groupActivated: activation === "always",
+    });
+
+  if (!shouldSendReaction()) {
+    return null;
+  }
+
+  params.info(
+    { chatId: params.msg.chatId, messageId: params.msg.id, emoji },
+    "sending ack reaction",
+  );
+  const sender = getSenderIdentity(params.msg);
+  const reactionOptions = {
+    verbose: params.verbose,
+    fromMe: false,
+    ...(sender.jid ? { participant: sender.jid } : {}),
+    ...(params.accountId ? { accountId: params.accountId } : {}),
+    cfg: params.cfg,
+  };
+  return createAckReactionHandle({
+    ackReactionValue: emoji,
+    send: () => sendReactionWhatsApp(params.msg.chatId, params.msg.id!, emoji, reactionOptions),
+    remove: () => sendReactionWhatsApp(params.msg.chatId, params.msg.id!, "", reactionOptions),
+    onSendError: (err) => {
+      params.warn(
+        {
+          error: formatError(err),
+          chatId: params.msg.chatId,
+          messageId: params.msg.id,
+        },
+        "failed to send ack reaction",
+      );
+      logVerbose(`WhatsApp ack reaction failed for chat ${params.msg.chatId}: ${formatError(err)}`);
+    },
+  });
+}

package/src/auto-reply/monitor/audio-preflight.runtime.ts

@@ -0,0 +1,9 @@
+import { transcribeFirstAudio as transcribeFirstAudioImpl } from "openclaw/plugin-sdk/media-runtime";
+
+type TranscribeFirstAudio = typeof import("openclaw/plugin-sdk/media-runtime").transcribeFirstAudio;
+
+export async function transcribeFirstAudio(
+  ...args: Parameters<TranscribeFirstAudio>
+): ReturnType<TranscribeFirstAudio> {
+  return await transcribeFirstAudioImpl(...args);
+}

package/src/auto-reply/monitor/broadcast.ts

@@ -0,0 +1,153 @@
+import type { AckReactionHandle } from "openclaw/plugin-sdk/channel-feedback";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { buildAgentSessionKey, deriveLastRoutePolicy } from "openclaw/plugin-sdk/routing";
+import {
+  buildAgentMainSessionKey,
+  DEFAULT_MAIN_KEY,
+  normalizeAgentId,
+} from "openclaw/plugin-sdk/routing";
+import { resolveWhatsAppGroupSessionRoute } from "../../group-session-key.js";
+import { formatError } from "../../session.js";
+import { whatsappInboundLog } from "../loggers.js";
+import type { WebInboundMsg } from "../types.js";
+import type { GroupHistoryEntry } from "./inbound-context.js";
+
+function buildBroadcastRouteKeys(params: {
+  cfg: OpenClawConfig;
+  msg: WebInboundMsg;
+  route: ReturnType<typeof resolveAgentRoute>;
+  peerId: string;
+  agentId: string;
+}) {
+  const sessionKey = buildAgentSessionKey({
+    agentId: params.agentId,
+    channel: "whatsapp",
+    accountId: params.route.accountId,
+    peer: {
+      kind: params.msg.chatType === "group" ? "group" : "direct",
+      id: params.peerId,
+    },
+    dmScope: params.cfg.session?.dmScope,
+    identityLinks: params.cfg.session?.identityLinks,
+  });
+  const mainSessionKey = buildAgentMainSessionKey({
+    agentId: params.agentId,
+    mainKey: DEFAULT_MAIN_KEY,
+  });
+
+  return {
+    sessionKey,
+    mainSessionKey,
+    lastRoutePolicy: deriveLastRoutePolicy({
+      sessionKey,
+      mainSessionKey,
+    }),
+  };
+}
+
+export async function maybeBroadcastMessage(params: {
+  cfg: OpenClawConfig;
+  msg: WebInboundMsg;
+  peerId: string;
+  route: ReturnType<typeof resolveAgentRoute>;
+  groupHistoryKey: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  processMessage: (
+    msg: WebInboundMsg,
+    route: ReturnType<typeof resolveAgentRoute>,
+    groupHistoryKey: string,
+    opts?: {
+      groupHistory?: GroupHistoryEntry[];
+      suppressGroupHistoryClear?: boolean;
+      preflightAudioTranscript?: string | null;
+      ackAlreadySent?: boolean;
+      ackReaction?: AckReactionHandle | null;
+    },
+  ) => Promise<boolean>;
+  preflightAudioTranscript?: string | null;
+  ackAlreadySent?: boolean;
+  ackReaction?: AckReactionHandle | null;
+}) {
+  const broadcastAgents = params.cfg.broadcast?.[params.peerId];
+  if (!broadcastAgents || !Array.isArray(broadcastAgents)) {
+    return false;
+  }
+  if (broadcastAgents.length === 0) {
+    return false;
+  }
+
+  const strategy = params.cfg.broadcast?.strategy || "parallel";
+  whatsappInboundLog.info(`Broadcasting message to ${broadcastAgents.length} agents (${strategy})`);
+
+  const agentIds = params.cfg.agents?.list?.map((agent) => normalizeAgentId(agent.id));
+  const hasKnownAgents = (agentIds?.length ?? 0) > 0;
+  const groupHistorySnapshot =
+    params.msg.chatType === "group"
+      ? (params.groupHistories.get(params.groupHistoryKey) ?? [])
+      : undefined;
+
+  const processForAgent = async (agentId: string): Promise<boolean> => {
+    const normalizedAgentId = normalizeAgentId(agentId);
+    if (hasKnownAgents && !agentIds?.includes(normalizedAgentId)) {
+      whatsappInboundLog.warn(`Broadcast agent ${agentId} not found in agents.list; skipping`);
+      return false;
+    }
+    const routeKeys = buildBroadcastRouteKeys({
+      cfg: params.cfg,
+      msg: params.msg,
+      route: params.route,
+      peerId: params.peerId,
+      agentId: normalizedAgentId,
+    });
+    const baseAgentRoute = {
+      ...params.route,
+      agentId: normalizedAgentId,
+      ...routeKeys,
+    };
+    const agentRoute =
+      params.msg.chatType === "group"
+        ? resolveWhatsAppGroupSessionRoute(baseAgentRoute)
+        : baseAgentRoute;
+
+    try {
+      const opts: {
+        groupHistory?: GroupHistoryEntry[];
+        suppressGroupHistoryClear: true;
+        preflightAudioTranscript?: string | null;
+        ackAlreadySent?: boolean;
+        ackReaction?: AckReactionHandle | null;
+      } = {
+        groupHistory: groupHistorySnapshot,
+        suppressGroupHistoryClear: true,
+      };
+      if (params.preflightAudioTranscript !== undefined) {
+        opts.preflightAudioTranscript = params.preflightAudioTranscript;
+      }
+      if (params.ackAlreadySent === true) {
+        opts.ackAlreadySent = true;
+      }
+      if (params.ackReaction !== undefined) {
+        opts.ackReaction = params.ackReaction;
+      }
+      return await params.processMessage(params.msg, agentRoute, params.groupHistoryKey, opts);
+    } catch (err) {
+      whatsappInboundLog.error(`Broadcast agent ${agentId} failed: ${formatError(err)}`);
+      return false;
+    }
+  };
+
+  if (strategy === "sequential") {
+    for (const agentId of broadcastAgents) {
+      await processForAgent(agentId);
+    }
+  } else {
+    await Promise.allSettled(broadcastAgents.map(processForAgent));
+  }
+
+  if (params.msg.chatType === "group") {
+    params.groupHistories.set(params.groupHistoryKey, []);
+  }
+
+  return true;
+}

package/src/auto-reply/monitor/commands.ts

@@ -0,0 +1,19 @@
+export function stripMentionsForCommand(
+  text: string,
+  mentionRegexes: RegExp[],
+  selfE164?: string | null,
+) {
+  let result = text;
+  for (const re of mentionRegexes) {
+    result = result.replace(re, " ");
+  }
+  if (selfE164) {
+    // `selfE164` is usually like "+1234"; strip down to digits so we can match "+?1234" safely.
+    const digits = selfE164.replace(/\D/g, "");
+    if (digits) {
+      const pattern = new RegExp(`\\+?${digits}`, "g");
+      result = result.replace(pattern, " ");
+    }
+  }
+  return result.replace(/\s+/g, " ").trim();
+}

package/src/auto-reply/monitor/echo.ts

@@ -0,0 +1,64 @@
+export type EchoTracker = {
+  rememberText: (
+    text: string | undefined,
+    opts: {
+      combinedBody?: string;
+      combinedBodySessionKey?: string;
+      logVerboseMessage?: boolean;
+    },
+  ) => void;
+  has: (key: string) => boolean;
+  forget: (key: string) => void;
+  buildCombinedKey: (params: { sessionKey: string; combinedBody: string }) => string;
+};
+
+export function createEchoTracker(params: {
+  maxItems?: number;
+  logVerbose?: (msg: string) => void;
+}): EchoTracker {
+  const recentlySent = new Set<string>();
+  const maxItems = Math.max(1, params.maxItems ?? 100);
+
+  const buildCombinedKey = (p: { sessionKey: string; combinedBody: string }) =>
+    `combined:${p.sessionKey}:${p.combinedBody}`;
+
+  const trim = () => {
+    while (recentlySent.size > maxItems) {
+      const firstKey = recentlySent.values().next().value;
+      if (!firstKey) {
+        break;
+      }
+      recentlySent.delete(firstKey);
+    }
+  };
+
+  const rememberText: EchoTracker["rememberText"] = (text, opts) => {
+    if (!text) {
+      return;
+    }
+    recentlySent.add(text);
+    if (opts.combinedBody && opts.combinedBodySessionKey) {
+      recentlySent.add(
+        buildCombinedKey({
+          sessionKey: opts.combinedBodySessionKey,
+          combinedBody: opts.combinedBody,
+        }),
+      );
+    }
+    if (opts.logVerboseMessage) {
+      params.logVerbose?.(
+        `Added to echo detection set (size now: ${recentlySent.size}): ${text.slice(0, 50)}...`,
+      );
+    }
+    trim();
+  };
+
+  return {
+    rememberText,
+    has: (key) => recentlySent.has(key),
+    forget: (key) => {
+      recentlySent.delete(key);
+    },
+    buildCombinedKey,
+  };
+}

package/src/auto-reply/monitor/group-activation.runtime.ts

@@ -0,0 +1 @@
+export { normalizeGroupActivation } from "openclaw/plugin-sdk/group-activation";

package/src/auto-reply/monitor/group-activation.test.ts

@@ -0,0 +1,189 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadSessionStore } from "../config.runtime.js";
+import { resolveGroupActivationFor } from "./group-activation.js";
+
+const GROUP_CONVERSATION_ID = "123@g.us";
+const LEGACY_GROUP_SESSION_KEY = "agent:main:whatsapp:group:123@g.us";
+const WORK_GROUP_SESSION_KEY = "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work";
+
+type SessionStoreEntry = {
+  groupActivation?: unknown;
+  sessionId?: unknown;
+  updatedAt?: unknown;
+};
+
+async function makeSessionStore(
+  entries: Record<string, unknown> = {},
+): Promise<{ storePath: string; cleanup: () => Promise<void> }> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-session-"));
+  const storePath = path.join(dir, "sessions.json");
+  await fs.writeFile(storePath, JSON.stringify(entries));
+  return {
+    storePath,
+    cleanup: async () => {
+      await fs.rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+const resolveWorkGroupActivation = (storePath: string) =>
+  resolveGroupActivationFor({
+    cfg: {
+      channels: {
+        whatsapp: {
+          accounts: {
+            work: {},
+          },
+        },
+      },
+      session: { store: storePath },
+    } as never,
+    accountId: "work",
+    agentId: "main",
+    sessionKey: WORK_GROUP_SESSION_KEY,
+    conversationId: GROUP_CONVERSATION_ID,
+  });
+
+const expectWorkGroupActivationEntry = async (
+  storePath: string,
+  assertEntry?: (entry: SessionStoreEntry | undefined) => void,
+) => {
+  await vi.waitFor(() => {
+    const scopedEntry = loadSessionStore(storePath, { skipCache: true })[WORK_GROUP_SESSION_KEY];
+    expect(scopedEntry?.groupActivation).toBe("always");
+    assertEntry?.(scopedEntry);
+  });
+};
+
+const expectResolvedWorkGroupActivation = async (
+  storePath: string,
+  assertEntry?: (entry: SessionStoreEntry | undefined) => void,
+) => {
+  const activation = await resolveWorkGroupActivation(storePath);
+  expect(activation).toBe("always");
+  await expectWorkGroupActivationEntry(storePath, assertEntry);
+};
+
+describe("resolveGroupActivationFor", () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      await cleanups.pop()?.();
+    }
+  });
+
+  it("reads legacy named-account group activation and backfills the scoped key", async () => {
+    const { storePath, cleanup } = await makeSessionStore({
+      [LEGACY_GROUP_SESSION_KEY]: {
+        groupActivation: "always",
+        sessionId: "legacy-session",
+        updatedAt: 123,
+      },
+    });
+    cleanups.push(cleanup);
+
+    await expectResolvedWorkGroupActivation(storePath, (scopedEntry) => {
+      expect(scopedEntry?.sessionId).toBeUndefined();
+      expect(scopedEntry?.updatedAt).toBeUndefined();
+    });
+  });
+
+  it("preserves legacy group activation when the scoped entry already exists without activation", async () => {
+    const { storePath, cleanup } = await makeSessionStore({
+      [LEGACY_GROUP_SESSION_KEY]: {
+        groupActivation: "always",
+      },
+      [WORK_GROUP_SESSION_KEY]: {
+        sessionId: "scoped-session",
+      },
+    });
+    cleanups.push(cleanup);
+
+    await expectResolvedWorkGroupActivation(storePath, (scopedEntry) => {
+      expect(scopedEntry?.sessionId).toBe("scoped-session");
+    });
+  });
+
+  it("does not wake the default account from an activation-only legacy group entry in multi-account setups", async () => {
+    const { storePath, cleanup } = await makeSessionStore({
+      [LEGACY_GROUP_SESSION_KEY]: {
+        groupActivation: "always",
+      },
+    });
+    cleanups.push(cleanup);
+
+    const cfg = {
+      channels: {
+        whatsapp: {
+          groups: {
+            "*": {
+              requireMention: true,
+            },
+          },
+          accounts: {
+            work: {},
+          },
+        },
+      },
+      session: { store: storePath },
+    } as never;
+
+    const workActivation = await resolveGroupActivationFor({
+      cfg,
+      accountId: "work",
+      agentId: "main",
+      sessionKey: WORK_GROUP_SESSION_KEY,
+      conversationId: GROUP_CONVERSATION_ID,
+    });
+
+    expect(workActivation).toBe("always");
+
+    const defaultActivation = await resolveGroupActivationFor({
+      cfg,
+      accountId: "default",
+      agentId: "main",
+      sessionKey: LEGACY_GROUP_SESSION_KEY,
+      conversationId: GROUP_CONVERSATION_ID,
+    });
+
+    expect(defaultActivation).toBe("mention");
+    await expectWorkGroupActivationEntry(storePath);
+  });
+
+  it("does not treat mixed-case default account keys as named accounts", async () => {
+    const { storePath, cleanup } = await makeSessionStore({
+      [LEGACY_GROUP_SESSION_KEY]: {
+        groupActivation: "always",
+      },
+    });
+    cleanups.push(cleanup);
+
+    const activation = await resolveGroupActivationFor({
+      cfg: {
+        channels: {
+          whatsapp: {
+            groups: {
+              "*": {
+                requireMention: true,
+              },
+            },
+            accounts: {
+              Default: {},
+            },
+          },
+        },
+        session: { store: storePath },
+      } as never,
+      accountId: "default",
+      agentId: "main",
+      sessionKey: LEGACY_GROUP_SESSION_KEY,
+      conversationId: GROUP_CONVERSATION_ID,
+    });
+
+    expect(activation).toBe("always");
+  });
+});

package/src/auto-reply/monitor/group-activation.ts

@@ -0,0 +1,73 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
+import { updateSessionStore } from "openclaw/plugin-sdk/session-store-runtime";
+import { resolveWhatsAppLegacyGroupSessionKey } from "../../group-session-key.js";
+import { resolveWhatsAppInboundPolicy } from "../../inbound-policy.js";
+import { loadSessionStore, resolveStorePath } from "../config.runtime.js";
+import { normalizeGroupActivation } from "./group-activation.runtime.js";
+
+function hasNamedWhatsAppAccounts(cfg: OpenClawConfig) {
+  const accountIds = Object.keys(cfg.channels?.whatsapp?.accounts ?? {});
+  return accountIds.some((accountId) => normalizeAccountId(accountId) !== DEFAULT_ACCOUNT_ID);
+}
+
+function isActivationOnlyEntry(
+  entry:
+    | {
+        groupActivation?: unknown;
+        sessionId?: unknown;
+        updatedAt?: unknown;
+      }
+    | undefined,
+) {
+  return (
+    entry?.groupActivation !== undefined &&
+    typeof entry?.sessionId !== "string" &&
+    typeof entry?.updatedAt !== "number"
+  );
+}
+
+export async function resolveGroupActivationFor(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  agentId: string;
+  sessionKey: string;
+  conversationId: string;
+}) {
+  const storePath = resolveStorePath(params.cfg.session?.store, {
+    agentId: params.agentId,
+  });
+  const store = loadSessionStore(storePath);
+  const legacySessionKey = resolveWhatsAppLegacyGroupSessionKey({
+    sessionKey: params.sessionKey,
+    accountId: params.accountId,
+  });
+  const legacyEntry = legacySessionKey ? store[legacySessionKey] : undefined;
+  const scopedEntry = store[params.sessionKey];
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const ignoreScopedActivation =
+    normalizedAccountId === DEFAULT_ACCOUNT_ID &&
+    hasNamedWhatsAppAccounts(params.cfg) &&
+    isActivationOnlyEntry(scopedEntry);
+  const activation =
+    (ignoreScopedActivation ? undefined : scopedEntry?.groupActivation) ??
+    legacyEntry?.groupActivation;
+  if (activation !== undefined && scopedEntry?.groupActivation === undefined) {
+    await updateSessionStore(storePath, (nextStore) => {
+      const nextScopedEntry = nextStore[params.sessionKey];
+      if (nextScopedEntry?.groupActivation !== undefined) {
+        return;
+      }
+      nextStore[params.sessionKey] = {
+        ...nextScopedEntry,
+        groupActivation: activation,
+      };
+    });
+  }
+  const requireMention = resolveWhatsAppInboundPolicy({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  }).resolveConversationRequireMention(params.conversationId);
+  const defaultActivation = !requireMention ? "always" : "mention";
+  return normalizeGroupActivation(activation) ?? defaultActivation;
+}