@openclaw/whatsapp 2026.5.1-beta.1

package/src/auto-reply/monitor/group-gating.audio-preflight.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./group-activation.js", () => ({
+  resolveGroupActivationFor: vi.fn(async () => "mention"),
+}));
+
+import type { MentionConfig } from "../mentions.js";
+import type { WebInboundMsg } from "../types.js";
+import { applyGroupGating, type GroupHistoryEntry } from "./group-gating.js";
+
+function makeGroupAudioMsg(): WebInboundMsg {
+  return {
+    id: "msg-1",
+    from: "1203630@g.us",
+    to: "+15550000001",
+    body: "<media:audio>",
+    chatId: "1203630@g.us",
+    chatType: "group",
+    conversationId: "1203630@g.us",
+    mediaType: "audio/ogg; codecs=opus",
+    mediaPath: "/tmp/voice.ogg",
+    timestamp: 1700000000,
+    accountId: "default",
+    sender: { e164: "+15550000002", name: "Alice" },
+  } as WebInboundMsg;
+}
+
+function makeParams(msg: WebInboundMsg, groupHistories: Map<string, GroupHistoryEntry[]>) {
+  return {
+    cfg: {
+      channels: {
+        whatsapp: {
+          groupPolicy: "open",
+        },
+      },
+      messages: {
+        groupChat: {
+          mentionPatterns: ["\\bopenclaw\\b"],
+        },
+      },
+    } as never,
+    msg,
+    conversationId: "1203630@g.us",
+    groupHistoryKey: "whatsapp:group:1203630",
+    agentId: "main",
+    sessionKey: "agent:main:whatsapp:group:1203630",
+    baseMentionConfig: { mentionRegexes: [/\bopenclaw\b/i] } satisfies MentionConfig,
+    groupHistories,
+    groupHistoryLimit: 20,
+    groupMemberNames: new Map<string, Map<string, string>>(),
+    logVerbose: vi.fn(),
+    replyLogger: { debug: vi.fn() },
+  };
+}
+
+describe("applyGroupGating audio preflight mention text", () => {
+  let groupHistories: Map<string, GroupHistoryEntry[]>;
+
+  beforeEach(() => {
+    groupHistories = new Map();
+  });
+
+  it("defers a missing mention without storing placeholder history", async () => {
+    const msg = makeGroupAudioMsg();
+
+    const result = await applyGroupGating({
+      ...makeParams(msg, groupHistories),
+      deferMissingMention: true,
+    });
+
+    expect(result).toEqual({ shouldProcess: false, needsMentionText: true });
+    expect(groupHistories.get("whatsapp:group:1203630")).toBeUndefined();
+  });
+
+  it("accepts voice transcript text that satisfies mention gating", async () => {
+    const msg = makeGroupAudioMsg();
+
+    const result = await applyGroupGating({
+      ...makeParams(msg, groupHistories),
+      mentionText: "openclaw please summarize the thread",
+    });
+
+    expect(result).toEqual({ shouldProcess: true });
+    expect(msg.wasMentioned).toBe(true);
+    expect(groupHistories.get("whatsapp:group:1203630")).toBeUndefined();
+  });
+
+  it("stores transcript text instead of the audio placeholder when mention is still missing", async () => {
+    const msg = makeGroupAudioMsg();
+
+    const result = await applyGroupGating({
+      ...makeParams(msg, groupHistories),
+      mentionText: "please summarize the thread",
+    });
+
+    expect(result).toEqual({ shouldProcess: false });
+    expect(groupHistories.get("whatsapp:group:1203630")).toEqual([
+      expect.objectContaining({
+        body: "please summarize the thread",
+      }),
+    ]);
+  });
+});

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

@@ -0,0 +1,8 @@
+export {
+  implicitMentionKindWhen,
+  resolveInboundMentionDecision,
+} from "openclaw/plugin-sdk/channel-mention-gating";
+export { hasControlCommand } from "openclaw/plugin-sdk/command-detection";
+export { recordPendingHistoryEntryIfEnabled } from "openclaw/plugin-sdk/reply-history";
+export { parseActivationCommand } from "openclaw/plugin-sdk/group-activation";
+export { normalizeE164 } from "../../text-runtime.js";

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

@@ -0,0 +1,217 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  getPrimaryIdentityId,
+  getReplyContext,
+  getSelfIdentity,
+  getSenderIdentity,
+  identitiesOverlap,
+} from "../../identity.js";
+import { resolveWhatsAppInboundPolicy } from "../../inbound-policy.js";
+import type { MentionConfig } from "../mentions.js";
+import { buildMentionConfig, debugMention, resolveOwnerList } from "../mentions.js";
+import type { WebInboundMsg } from "../types.js";
+import { stripMentionsForCommand } from "./commands.js";
+import { resolveGroupActivationFor } from "./group-activation.js";
+import {
+  hasControlCommand,
+  implicitMentionKindWhen,
+  normalizeE164,
+  parseActivationCommand,
+  recordPendingHistoryEntryIfEnabled,
+  resolveInboundMentionDecision,
+} from "./group-gating.runtime.js";
+import { noteGroupMember } from "./group-members.js";
+
+export type GroupHistoryEntry = {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  id?: string;
+  senderJid?: string;
+};
+
+type ApplyGroupGatingParams = {
+  cfg: OpenClawConfig;
+  msg: WebInboundMsg;
+  mentionText?: string;
+  deferMissingMention?: boolean;
+  conversationId: string;
+  groupHistoryKey: string;
+  agentId: string;
+  sessionKey: string;
+  baseMentionConfig: MentionConfig;
+  authDir?: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  groupHistoryLimit: number;
+  groupMemberNames: Map<string, Map<string, string>>;
+  selfChatMode?: boolean;
+  logVerbose: (msg: string) => void;
+  replyLogger: { debug: (obj: unknown, msg: string) => void };
+};
+
+function isOwnerSender(baseMentionConfig: MentionConfig, msg: WebInboundMsg) {
+  const sender = normalizeE164(getSenderIdentity(msg).e164 ?? "");
+  if (!sender) {
+    return false;
+  }
+  const owners = resolveOwnerList(baseMentionConfig, getSelfIdentity(msg).e164 ?? undefined);
+  return owners.includes(sender);
+}
+
+function recordPendingGroupHistoryEntry(params: {
+  msg: WebInboundMsg;
+  body?: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  groupHistoryKey: string;
+  groupHistoryLimit: number;
+}) {
+  const senderIdentity = getSenderIdentity(params.msg);
+  const sender =
+    senderIdentity.name && senderIdentity.e164
+      ? `${senderIdentity.name} (${senderIdentity.e164})`
+      : (senderIdentity.name ??
+        senderIdentity.e164 ??
+        getPrimaryIdentityId(senderIdentity) ??
+        "Unknown");
+  recordPendingHistoryEntryIfEnabled({
+    historyMap: params.groupHistories,
+    historyKey: params.groupHistoryKey,
+    limit: params.groupHistoryLimit,
+    entry: {
+      sender,
+      body: params.body ?? params.msg.body,
+      timestamp: params.msg.timestamp,
+      id: params.msg.id,
+      senderJid: senderIdentity.jid ?? params.msg.senderJid,
+    },
+  });
+}
+
+function skipGroupMessageAndStoreHistory(
+  params: ApplyGroupGatingParams,
+  verboseMessage: string,
+  body?: string,
+) {
+  params.logVerbose(verboseMessage);
+  recordPendingGroupHistoryEntry({
+    msg: params.msg,
+    body,
+    groupHistories: params.groupHistories,
+    groupHistoryKey: params.groupHistoryKey,
+    groupHistoryLimit: params.groupHistoryLimit,
+  });
+  return { shouldProcess: false } as const;
+}
+
+export async function applyGroupGating(params: ApplyGroupGatingParams) {
+  const sender = getSenderIdentity(params.msg);
+  const self = getSelfIdentity(params.msg, params.authDir);
+  const inboundPolicy = resolveWhatsAppInboundPolicy({
+    cfg: params.cfg,
+    accountId: params.msg.accountId,
+    selfE164: self.e164 ?? null,
+  });
+  const conversationGroupPolicy = inboundPolicy.resolveConversationGroupPolicy(
+    params.conversationId,
+  );
+  if (conversationGroupPolicy.allowlistEnabled && !conversationGroupPolicy.allowed) {
+    params.logVerbose(`Skipping group message ${params.conversationId} (not in allowlist)`);
+    return { shouldProcess: false };
+  }
+
+  noteGroupMember(
+    params.groupMemberNames,
+    params.groupHistoryKey,
+    sender.e164 ?? undefined,
+    sender.name ?? undefined,
+  );
+
+  const baseMentionConfig = {
+    ...params.baseMentionConfig,
+    allowFrom: inboundPolicy.configuredAllowFrom,
+  };
+  const mentionConfig = {
+    ...buildMentionConfig(params.cfg, params.agentId),
+    allowFrom: inboundPolicy.configuredAllowFrom,
+  };
+  const mentionMsg =
+    params.mentionText !== undefined ? { ...params.msg, body: params.mentionText } : params.msg;
+  const commandBody = stripMentionsForCommand(
+    mentionMsg.body,
+    mentionConfig.mentionRegexes,
+    self.e164,
+  );
+  const activationCommand = parseActivationCommand(commandBody);
+  const owner = isOwnerSender(baseMentionConfig, params.msg);
+  const shouldBypassMention = owner && hasControlCommand(commandBody, params.cfg);
+
+  if (activationCommand.hasCommand && !owner) {
+    return skipGroupMessageAndStoreHistory(
+      params,
+      `Ignoring /activation from non-owner in group ${params.conversationId}`,
+    );
+  }
+
+  const mentionDebug = debugMention(mentionMsg, mentionConfig, params.authDir);
+  params.replyLogger.debug(
+    {
+      conversationId: params.conversationId,
+      wasMentioned: mentionDebug.wasMentioned,
+      ...mentionDebug.details,
+    },
+    "group mention debug",
+  );
+  const wasMentioned = mentionDebug.wasMentioned;
+  const activation = await resolveGroupActivationFor({
+    cfg: params.cfg,
+    accountId: inboundPolicy.account.accountId,
+    agentId: params.agentId,
+    sessionKey: params.sessionKey,
+    conversationId: params.conversationId,
+  });
+  const requireMention = activation !== "always";
+  const replyContext = getReplyContext(params.msg, params.authDir);
+  const sharedNumberSelfChat = params.selfChatMode === true;
+  // Detect reply-to-bot: compare JIDs, LIDs, and E.164 numbers.
+  // WhatsApp may report the quoted message sender as either a phone JID
+  // (xxxxx@s.whatsapp.net) or a LID (xxxxx@lid), so we compare both.
+  // But in shared-number/selfChatMode setups, replies from the same self number
+  // should not count as implicit bot mentions unless the message explicitly
+  // mentioned the bot in text.
+  const implicitReplyToSelf = sharedNumberSelfChat && identitiesOverlap(self, sender);
+  const implicitMentionKinds = implicitMentionKindWhen(
+    "quoted_bot",
+    !implicitReplyToSelf && identitiesOverlap(self, replyContext?.sender),
+  );
+  const mentionDecision = resolveInboundMentionDecision({
+    facts: {
+      canDetectMention: true,
+      wasMentioned,
+      implicitMentionKinds,
+    },
+    policy: {
+      isGroup: true,
+      requireMention,
+      allowTextCommands: false,
+      hasControlCommand: false,
+      commandAuthorized: false,
+    },
+  });
+  const effectiveWasMentioned = mentionDecision.effectiveWasMentioned || shouldBypassMention;
+  params.msg.wasMentioned = effectiveWasMentioned;
+  if (!shouldBypassMention && requireMention && mentionDecision.shouldSkip) {
+    if (params.deferMissingMention === true) {
+      params.logVerbose(
+        `Deferring group mention skip until audio preflight completes in ${params.conversationId}`,
+      );
+      return { shouldProcess: false, needsMentionText: true } as const;
+    }
+    return skipGroupMessageAndStoreHistory(
+      params,
+      `Group message stored for context (no mention detected) in ${params.conversationId}: ${mentionMsg.body}`,
+      params.mentionText,
+    );
+  }
+
+  return { shouldProcess: true };
+}

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { formatGroupMembers, noteGroupMember } from "./group-members.js";
+
+describe("noteGroupMember", () => {
+  it("normalizes member phone numbers before storing", () => {
+    const groupMemberNames = new Map<string, Map<string, string>>();
+
+    noteGroupMember(groupMemberNames, "g1", "+1 (555) 123-4567", "Alice");
+
+    expect(groupMemberNames.get("g1")?.get("+15551234567")).toBe("Alice");
+  });
+
+  it("ignores incomplete member values", () => {
+    const groupMemberNames = new Map<string, Map<string, string>>();
+
+    noteGroupMember(groupMemberNames, "g1", undefined, "Alice");
+    noteGroupMember(groupMemberNames, "g1", "+15551234567", undefined);
+
+    expect(groupMemberNames.get("g1")).toBeUndefined();
+  });
+});
+
+describe("formatGroupMembers", () => {
+  it("deduplicates participants and appends named roster members", () => {
+    const roster = new Map<string, string>([
+      ["+16660000000", "Bob"],
+      ["+17770000000", "Carol"],
+    ]);
+
+    const formatted = formatGroupMembers({
+      participants: ["+1 (555) 000-0000", "+15550000000", "+16660000000"],
+      roster,
+    });
+
+    expect(formatted).toBe("+15550000000, Bob (+16660000000), Carol (+17770000000)");
+  });
+
+  it("falls back to sender when no participants or roster are available", () => {
+    const formatted = formatGroupMembers({
+      participants: [],
+      roster: undefined,
+      fallbackE164: "+1 (555) 222-3333",
+    });
+
+    expect(formatted).toBe("+15552223333");
+  });
+
+  it("returns undefined when no members can be resolved", () => {
+    expect(
+      formatGroupMembers({
+        participants: [],
+        roster: undefined,
+      }),
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,65 @@
+import { normalizeE164 } from "../../text-runtime.js";
+
+function appendNormalizedUnique(entries: Iterable<string>, seen: Set<string>, ordered: string[]) {
+  for (const entry of entries) {
+    const normalized = normalizeE164(entry) ?? entry;
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    ordered.push(normalized);
+  }
+}
+
+export function noteGroupMember(
+  groupMemberNames: Map<string, Map<string, string>>,
+  conversationId: string,
+  e164?: string,
+  name?: string,
+) {
+  if (!e164 || !name) {
+    return;
+  }
+  const normalized = normalizeE164(e164);
+  const key = normalized ?? e164;
+  if (!key) {
+    return;
+  }
+  let roster = groupMemberNames.get(conversationId);
+  if (!roster) {
+    roster = new Map();
+    groupMemberNames.set(conversationId, roster);
+  }
+  roster.set(key, name);
+}
+
+export function formatGroupMembers(params: {
+  participants: string[] | undefined;
+  roster: Map<string, string> | undefined;
+  fallbackE164?: string;
+}) {
+  const { participants, roster, fallbackE164 } = params;
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  if (participants?.length) {
+    appendNormalizedUnique(participants, seen, ordered);
+  }
+  if (roster) {
+    appendNormalizedUnique(roster.keys(), seen, ordered);
+  }
+  if (ordered.length === 0 && fallbackE164) {
+    const normalized = normalizeE164(fallbackE164) ?? fallbackE164;
+    if (normalized) {
+      ordered.push(normalized);
+    }
+  }
+  if (ordered.length === 0) {
+    return undefined;
+  }
+  return ordered
+    .map((entry) => {
+      const name = roster?.get(entry);
+      return name ? `${name} (${entry})` : entry;
+    })
+    .join(", ");
+}

package/src/auto-reply/monitor/inbound-context.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import type { WhatsAppSendResult } from "../../inbound/send-result.js";
+import {
+  resolveVisibleWhatsAppGroupHistory,
+  resolveVisibleWhatsAppReplyContext,
+} from "./inbound-context.js";
+
+type ReplyContextParams = Parameters<typeof resolveVisibleWhatsAppReplyContext>[0];
+
+function acceptedSendResult(kind: "media" | "text", id: string): WhatsAppSendResult {
+  return {
+    kind,
+    messageId: id,
+    messageIds: [id],
+    keys: [{ id }],
+    providerAccepted: true,
+  };
+}
+
+const makeBlockedQuotedReplyMessage = (id: string): ReplyContextParams["msg"] => ({
+  id,
+  from: "123@g.us",
+  conversationId: "123@g.us",
+  to: "+2000",
+  accountId: "default",
+  chatType: "group",
+  chatId: "123@g.us",
+  body: "Current message",
+  senderName: "Alice",
+  senderJid: "111@s.whatsapp.net",
+  senderE164: "+111",
+  selfE164: "+999",
+  replyToId: "blocked-reply",
+  replyToBody: "Blocked quoted text",
+  replyToSender: "Mallory (+999)",
+  replyToSenderJid: "999@s.whatsapp.net",
+  sendComposing: async () => {},
+  reply: async () => acceptedSendResult("text", "r1"),
+  sendMedia: async () => acceptedSendResult("media", "m1"),
+});
+
+describe("whatsapp inbound context visibility", () => {
+  it("filters non-allowlisted group history from supplemental context", () => {
+    const history = resolveVisibleWhatsAppGroupHistory({
+      history: [
+        {
+          sender: "Alice (+111)",
+          body: "Allowed context",
+          senderJid: "111@s.whatsapp.net",
+        },
+        {
+          sender: "Mallory (+999)",
+          body: "Blocked context",
+          senderJid: "999@s.whatsapp.net",
+        },
+      ],
+      mode: "allowlist",
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+111"],
+    });
+
+    expect(history).toEqual([
+      expect.objectContaining({
+        sender: "Alice (+111)",
+        body: "Allowed context",
+      }),
+    ]);
+  });
+
+  it("redacts blocked quoted replies in allowlist mode", () => {
+    const reply = resolveVisibleWhatsAppReplyContext({
+      msg: makeBlockedQuotedReplyMessage("msg-reply-1"),
+      mode: "allowlist",
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+111"],
+    });
+
+    expect(reply).toBeNull();
+  });
+
+  it("keeps blocked quoted replies in allowlist_quote mode", () => {
+    const reply = resolveVisibleWhatsAppReplyContext({
+      msg: makeBlockedQuotedReplyMessage("msg-reply-2"),
+      mode: "allowlist_quote",
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+111"],
+    });
+
+    expect(reply).toMatchObject({
+      id: "blocked-reply",
+      body: "Blocked quoted text",
+      sender: expect.objectContaining({
+        label: "Mallory (+999)",
+      }),
+    });
+  });
+});

package/src/auto-reply/monitor/inbound-context.ts

@@ -0,0 +1,92 @@
+import {
+  evaluateSupplementalContextVisibility,
+  filterSupplementalContextItems,
+} from "openclaw/plugin-sdk/security-runtime";
+import {
+  getComparableIdentityValues,
+  getReplyContext,
+  type WhatsAppIdentity,
+  type WhatsAppReplyContext,
+} from "../../identity.js";
+import { normalizeE164 } from "../../text-runtime.js";
+import type { WebInboundMsg } from "../types.js";
+
+export type GroupHistoryEntry = {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  id?: string;
+  senderJid?: string;
+};
+
+type ContextVisibilityMode = "all" | "allowlist" | "allowlist_quote";
+
+function isWhatsAppSupplementalSenderAllowed(params: {
+  allowFrom: string[];
+  sender?: WhatsAppIdentity | null;
+}): boolean {
+  if (params.allowFrom.includes("*")) {
+    return true;
+  }
+  const senderValues = new Set(getComparableIdentityValues(params.sender));
+  if (senderValues.size === 0) {
+    return false;
+  }
+  for (const entry of params.allowFrom) {
+    const rawEntry = entry.trim();
+    if (!rawEntry) {
+      continue;
+    }
+    const normalizedEntry = normalizeE164(rawEntry);
+    if ((normalizedEntry && senderValues.has(normalizedEntry)) || senderValues.has(rawEntry)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function resolveVisibleWhatsAppGroupHistory(params: {
+  history: GroupHistoryEntry[];
+  mode: ContextVisibilityMode;
+  groupPolicy: "open" | "allowlist" | "disabled";
+  groupAllowFrom: string[];
+}): GroupHistoryEntry[] {
+  if (params.groupPolicy !== "allowlist") {
+    return params.history;
+  }
+  return filterSupplementalContextItems({
+    items: params.history,
+    mode: params.mode,
+    kind: "history",
+    isSenderAllowed: (entry) =>
+      isWhatsAppSupplementalSenderAllowed({
+        allowFrom: params.groupAllowFrom,
+        sender: entry.senderJid ? { jid: entry.senderJid } : null,
+      }),
+  }).items;
+}
+
+export function resolveVisibleWhatsAppReplyContext(params: {
+  msg: WebInboundMsg;
+  authDir?: string;
+  mode: ContextVisibilityMode;
+  groupPolicy: "open" | "allowlist" | "disabled";
+  groupAllowFrom: string[];
+}): WhatsAppReplyContext | null {
+  const replyTo = getReplyContext(params.msg, params.authDir);
+  if (!replyTo) {
+    return null;
+  }
+  const include = evaluateSupplementalContextVisibility({
+    mode: params.mode,
+    kind: "quote",
+    senderAllowed:
+      params.msg.chatType !== "group" || params.groupPolicy !== "allowlist"
+        ? true
+        : isWhatsAppSupplementalSenderAllowed({
+            allowFrom: params.groupAllowFrom,
+            sender: replyTo.sender,
+          }),
+  }).include;
+  return include ? replyTo : null;
+}

package/src/auto-reply/monitor/inbound-dispatch.runtime.ts

@@ -0,0 +1,21 @@
+export {
+  createChannelReplyPipeline,
+  dispatchReplyWithBufferedBlockDispatcher,
+  finalizeInboundContext,
+  getAgentScopedMediaLocalRoots,
+  jidToE164,
+  logVerbose,
+  resolveChunkMode,
+  resolveIdentityNamePrefix,
+  resolveInboundLastRouteSessionKey,
+  resolveMarkdownTableMode,
+  resolveSendableOutboundReplyParts,
+  resolveTextChunkLimit,
+  shouldLogVerbose,
+  toLocationContext,
+  type getChildLogger,
+  type getReplyFromConfig,
+  type LoadConfigFn,
+  type ReplyPayload,
+  type resolveAgentRoute,
+} from "./runtime-api.js";