Add WhatsApp group listen windows

NehoraiHadad · NehoraiHadad · commit d508693dec15 · 2026-07-18T23:16:22.000+03:00
diff --git a/docs/channels/group-messages.md b/docs/channels/group-messages.md
@@ -19,6 +19,7 @@ Goal: let OpenClaw sit in WhatsApp groups, wake up only when pinged, and keep th
 ## Behavior
 
 - Activation modes: `mention` (default) or `always`. `mention` requires a ping: a real WhatsApp @-mention (`mentionedJids`), a configured regex pattern, the bot's E.164 digits anywhere in the text, or a quoted reply to one of the bot's messages (except shared-number self-chat setups). `always` wakes the agent on every message, but the injected group prompt tells it to reply only when it adds value and to return the exact silent token `NO_REPLY` (case-insensitive) otherwise. Defaults come from config (`channels.whatsapp.groups` `requireMention`) and can be overridden per group via `/activation`.
+- Temporary listen windows: groups that normally require mentions can opt into `listenAfterMentionMs`. After a valid mention, follow-up messages in the same allowed group are admitted until the window expires; each admitted follow-up extends the window up to `listenAfterMentionMaxMs`. `/activation mention` clears the current window.
 - Group allowlist: when `channels.whatsapp.groups` is set, only listed group JIDs are admitted (include `"*"` to allow all); messages from unlisted groups are dropped with a log hint.
 - Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
 - Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` (non-default accounts append `:thread:whatsapp-account-<accountId>`), so directives such as `/verbose on`, `/trace on`, or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched.
@@ -36,7 +37,11 @@ Make display-name pings work even when WhatsApp strips the visual `@` from the t
   channels: {
     whatsapp: {
       groups: {
-        "*": { requireMention: true },
+        "*": {
+          requireMention: true,
+          listenAfterMentionMs: 600000, // 10 minutes
+          listenAfterMentionMaxMs: 1800000, // 30 minutes
+        },
       },
       historyLimit: 50, // pending group context window (default 50)
     },
diff --git a/extensions/whatsapp/src/auto-reply/monitor/group-gating.audio-preflight.test.ts b/extensions/whatsapp/src/auto-reply/monitor/group-gating.audio-preflight.test.ts
@@ -1,5 +1,5 @@
 // Whatsapp tests cover group gating.audio preflight plugin behavior.
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("./group-activation.js", () => ({
   resolveGroupActivationFor: vi.fn(async () => "mention"),
@@ -10,6 +10,7 @@ import type { AdmittedWebInboundMessage } from "../../inbound/types.js";
 import type { MentionConfig } from "../mentions.js";
 import { resolveGroupActivationFor } from "./group-activation.js";
 import { applyGroupGating, type GroupHistoryEntry } from "./group-gating.js";
+import { clearGroupListenWindowsForTest } from "./group-listen-window.js";
 
 function makeGroupAudioMsg(): AdmittedWebInboundMessage {
   return createTestWebAudioInboundMessage({
@@ -67,7 +68,13 @@ describe("applyGroupGating audio preflight mention text", () => {
   let groupHistories: Map<string, GroupHistoryEntry[]>;
 
   beforeEach(() => {
+    clearGroupListenWindowsForTest();
     groupHistories = new Map();
+    vi.useFakeTimers({ now: new Date("2026-07-18T19:00:00.000Z") });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
   });
 
   it("defers a missing mention without storing placeholder history", async () => {
@@ -124,4 +131,110 @@ describe("applyGroupGating audio preflight mention text", () => {
       },
     ]);
   });
+
+  it("accepts follow-up messages during a configured listen-after-mention window", async () => {
+    const first = makeGroupAudioMsg();
+    const firstParams = makeParams(first, groupHistories);
+    (
+      firstParams.cfg as never as { channels: { whatsapp: { groups?: unknown } } }
+    ).channels.whatsapp.groups = {
+      "1203630@g.us": {
+        requireMention: true,
+        listenAfterMentionMs: 10 * 60 * 1000,
+        listenAfterMentionMaxMs: 30 * 60 * 1000,
+      },
+    };
+
+    await expect(
+      applyGroupGating({
+        ...firstParams,
+        mentionText: "openclaw please summarize the thread",
+      }),
+    ).resolves.toEqual({ shouldProcess: true });
+
+    vi.setSystemTime(new Date("2026-07-18T19:05:00.000Z"));
+    const followUp = makeGroupAudioMsg();
+    const followUpParams = makeParams(followUp, groupHistories);
+    (
+      followUpParams.cfg as never as { channels: { whatsapp: { groups?: unknown } } }
+    ).channels.whatsapp.groups = (
+      firstParams.cfg as never as { channels: { whatsapp: { groups?: unknown } } }
+    ).channels.whatsapp.groups;
+
+    await expect(applyGroupGating(followUpParams)).resolves.toEqual({ shouldProcess: true });
+    expect(followUp.groupMention).toEqual({ wasMentioned: false, requireMention: false });
+  });
+
+  it("stops extending the listen-after-mention window at the configured cap", async () => {
+    const first = makeGroupAudioMsg();
+    const firstParams = makeParams(first, groupHistories);
+    (
+      firstParams.cfg as never as { channels: { whatsapp: { groups?: unknown } } }
+    ).channels.whatsapp.groups = {
+      "*": {
+        listenAfterMentionMs: 10 * 60 * 1000,
+        listenAfterMentionMaxMs: 15 * 60 * 1000,
+      },
+    };
+
+    await applyGroupGating({
+      ...firstParams,
+      mentionText: "openclaw please summarize the thread",
+    });
+
+    vi.setSystemTime(new Date("2026-07-18T19:09:00.000Z"));
+    const extendingFollowUpParams = makeParams(makeGroupAudioMsg(), groupHistories);
+    extendingFollowUpParams.cfg = firstParams.cfg;
+    await expect(applyGroupGating(extendingFollowUpParams)).resolves.toEqual({
+      shouldProcess: true,
+    });
+
+    vi.setSystemTime(new Date("2026-07-18T19:14:00.000Z"));
+    const cappedFollowUpParams = makeParams(makeGroupAudioMsg(), groupHistories);
+    cappedFollowUpParams.cfg = firstParams.cfg;
+    await expect(applyGroupGating(cappedFollowUpParams)).resolves.toEqual({
+      shouldProcess: true,
+    });
+
+    vi.setSystemTime(new Date("2026-07-18T19:16:00.000Z"));
+    const expiredFollowUpParams = makeParams(makeGroupAudioMsg(), groupHistories);
+    expiredFollowUpParams.cfg = firstParams.cfg;
+    await expect(applyGroupGating(expiredFollowUpParams)).resolves.toEqual({
+      shouldProcess: false,
+    });
+  });
+
+  it("does not re-open a listen-after-mention window from /activation mention", async () => {
+    const first = makeGroupAudioMsg();
+    const firstParams = makeParams(first, groupHistories);
+    (
+      firstParams.cfg as never as { channels: { whatsapp: { groups?: unknown } } }
+    ).channels.whatsapp.groups = {
+      "*": {
+        listenAfterMentionMs: 10 * 60 * 1000,
+      },
+    };
+    (
+      firstParams.cfg as never as { channels: { whatsapp: { allowFrom?: string[] } } }
+    ).channels.whatsapp.allowFrom = ["+15550000002"];
+
+    await applyGroupGating({
+      ...firstParams,
+      mentionText: "openclaw please summarize the thread",
+    });
+
+    vi.setSystemTime(new Date("2026-07-18T19:05:00.000Z"));
+    const command = makeGroupAudioMsg();
+    command.payload.body = "/activation mention";
+    const commandParams = makeParams(command, groupHistories);
+    commandParams.cfg = firstParams.cfg;
+    await expect(applyGroupGating(commandParams)).resolves.toEqual({ shouldProcess: true });
+
+    vi.setSystemTime(new Date("2026-07-18T19:06:00.000Z"));
+    const followUpParams = makeParams(makeGroupAudioMsg(), groupHistories);
+    followUpParams.cfg = firstParams.cfg;
+    await expect(applyGroupGating(followUpParams)).resolves.toEqual({
+      shouldProcess: false,
+    });
+  });
 });
diff --git a/extensions/whatsapp/src/auto-reply/monitor/group-gating.ts b/extensions/whatsapp/src/auto-reply/monitor/group-gating.ts
@@ -25,6 +25,12 @@ import {
   createChannelHistoryWindow,
   resolveInboundMentionDecision,
 } from "./group-gating.runtime.js";
+import {
+  armGroupListenWindow,
+  clearGroupListenWindow,
+  resolveGroupListenWindowConfig,
+  resolveGroupListenWindowState,
+} from "./group-listen-window.js";
 import { noteGroupMember } from "./group-members.js";
 
 export type GroupHistoryEntry = {
@@ -216,7 +222,31 @@ export async function applyGroupGating(params: ApplyGroupGatingParams) {
     sessionKey: params.sessionKey,
     conversationId,
   });
-  const requireMention = activation !== "always";
+  const baseRequireMention = activation !== "always";
+  const listenWindowConfig = baseRequireMention
+    ? resolveGroupListenWindowConfig({
+        cfg: params.cfg,
+        accountId: inboundPolicy.account.accountId,
+        conversationId,
+      })
+    : undefined;
+  if (owner && activationCommand.hasCommand && activationCommand.mode === "mention") {
+    clearGroupListenWindow({
+      agentId: params.agentId,
+      accountId: inboundPolicy.account.accountId,
+      sessionKey: params.sessionKey,
+      conversationId,
+    });
+  }
+  const listenWindowActive =
+    listenWindowConfig !== undefined &&
+    resolveGroupListenWindowState({
+      agentId: params.agentId,
+      accountId: inboundPolicy.account.accountId,
+      sessionKey: params.sessionKey,
+      conversationId,
+    }) !== undefined;
+  const requireMention = baseRequireMention && !listenWindowActive;
   const replyContext = getReplyContext(params.msg, params.authDir);
   const sharedNumberSelfChat = params.selfChatMode === true;
   // Detect reply-to-bot: compare JIDs, LIDs, and E.164 numbers.
@@ -245,6 +275,19 @@ export async function applyGroupGating(params: ApplyGroupGatingParams) {
     },
   });
   const effectiveWasMentioned = mentionDecision.effectiveWasMentioned || shouldBypassMention;
+  if (
+    listenWindowConfig &&
+    !activationCommand.hasCommand &&
+    (effectiveWasMentioned || listenWindowActive)
+  ) {
+    armGroupListenWindow({
+      agentId: params.agentId,
+      accountId: inboundPolicy.account.accountId,
+      sessionKey: params.sessionKey,
+      conversationId,
+      config: listenWindowConfig,
+    });
+  }
   // Carry the session activation and mention result together. Dispatch needs
   // both facts to distinguish an always-on group from a blocked unmentioned turn.
   params.msg.groupMention = { wasMentioned: effectiveWasMentioned, requireMention };
diff --git a/extensions/whatsapp/src/auto-reply/monitor/group-listen-window.ts b/extensions/whatsapp/src/auto-reply/monitor/group-listen-window.ts
@@ -0,0 +1,112 @@
+// Whatsapp plugin module implements temporary group listen windows.
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { resolveWhatsAppAccount } from "../../accounts.js";
+import { resolveWhatsAppGroupConversationId } from "../../inbound/group-conversation.js";
+
+type ListenWindowConfig = {
+  durationMs: number;
+  maxMs: number;
+};
+
+type ListenWindowState = {
+  startedAtMs: number;
+  untilMs: number;
+};
+
+const listenWindows = new Map<string, ListenWindowState>();
+
+function normalizeMilliseconds(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : undefined;
+}
+
+function resolveGroupListenWindowKey(params: {
+  agentId: string;
+  accountId?: string | null;
+  sessionKey: string;
+  conversationId: string;
+}) {
+  return [
+    params.agentId,
+    params.accountId?.trim() || "default",
+    params.sessionKey,
+    resolveWhatsAppGroupConversationId(params.conversationId),
+  ].join("\u0000");
+}
+
+export function resolveGroupListenWindowConfig(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  conversationId: string;
+}): ListenWindowConfig | undefined {
+  const account = resolveWhatsAppAccount({ cfg: params.cfg, accountId: params.accountId });
+  const conversationId = resolveWhatsAppGroupConversationId(params.conversationId);
+  const group = account.groups?.[conversationId] ?? account.groups?.[params.conversationId];
+  const wildcardGroup = account.groups?.["*"];
+  const durationMs = normalizeMilliseconds(
+    group?.listenAfterMentionMs ?? wildcardGroup?.listenAfterMentionMs,
+  );
+  if (durationMs === undefined || durationMs <= 0) {
+    return undefined;
+  }
+  const configuredMaxMs = normalizeMilliseconds(
+    group?.listenAfterMentionMaxMs ?? wildcardGroup?.listenAfterMentionMaxMs,
+  );
+  return {
+    durationMs,
+    maxMs:
+      configuredMaxMs && configuredMaxMs > 0 ? Math.max(durationMs, configuredMaxMs) : durationMs,
+  };
+}
+
+export function resolveGroupListenWindowState(params: {
+  agentId: string;
+  accountId?: string | null;
+  sessionKey: string;
+  conversationId: string;
+  nowMs?: number;
+}): ListenWindowState | undefined {
+  const key = resolveGroupListenWindowKey(params);
+  const state = listenWindows.get(key);
+  if (!state) {
+    return undefined;
+  }
+  const nowMs = params.nowMs ?? Date.now();
+  if (state.untilMs <= nowMs) {
+    listenWindows.delete(key);
+    return undefined;
+  }
+  return state;
+}
+
+export function armGroupListenWindow(params: {
+  agentId: string;
+  accountId?: string | null;
+  sessionKey: string;
+  conversationId: string;
+  config: ListenWindowConfig;
+  nowMs?: number;
+}): ListenWindowState {
+  const nowMs = params.nowMs ?? Date.now();
+  const key = resolveGroupListenWindowKey(params);
+  const existing = listenWindows.get(key);
+  const startedAtMs = existing && existing.untilMs > nowMs ? existing.startedAtMs : nowMs;
+  const untilMs = Math.min(nowMs + params.config.durationMs, startedAtMs + params.config.maxMs);
+  const state = { startedAtMs, untilMs };
+  listenWindows.set(key, state);
+  return state;
+}
+
+export function clearGroupListenWindow(params: {
+  agentId: string;
+  accountId?: string | null;
+  sessionKey: string;
+  conversationId: string;
+}) {
+  listenWindows.delete(resolveGroupListenWindowKey(params));
+}
+
+export function clearGroupListenWindowsForTest() {
+  listenWindows.clear();
+}
diff --git a/extensions/whatsapp/src/config-schema.test.ts b/extensions/whatsapp/src/config-schema.test.ts
@@ -53,6 +53,32 @@ describe("whatsapp config schema", () => {
     }
   });
 
+  it("accepts listen-after-mention windows per group", () => {
+    const res = expectWhatsAppConfigValid({
+      groups: {
+        "1203630@g.us": {
+          requireMention: true,
+          listenAfterMentionMs: 600_000,
+          listenAfterMentionMaxMs: 1_800_000,
+        },
+      },
+      accounts: {
+        work: {
+          groups: {
+            "*": {
+              listenAfterMentionMs: 300_000,
+            },
+          },
+        },
+      },
+    });
+
+    if (res.success) {
+      expect(res.data.groups?.["1203630@g.us"]?.listenAfterMentionMs).toBe(600_000);
+      expect(res.data.accounts?.work?.groups?.["*"]?.listenAfterMentionMs).toBe(300_000);
+    }
+  });
+
   it("accepts textChunkLimit", () => {
     const res = expectWhatsAppConfigValid({
       allowFrom: ["+15555550123"],
diff --git a/src/config/types.whatsapp.ts b/src/config/types.whatsapp.ts
@@ -27,6 +27,10 @@ export type WhatsAppReactionLevel = ReactionLevel;
 
 export type WhatsAppGroupConfig = {
   requireMention?: boolean;
+  /** Temporarily accept follow-up messages after a mention in this group (ms). Default: disabled. */
+  listenAfterMentionMs?: number;
+  /** Maximum total duration for one listen-after-mention window (ms). */
+  listenAfterMentionMaxMs?: number;
   tools?: GroupToolPolicyConfig;
   toolsBySender?: GroupToolPolicyBySenderConfig;
   /** Optional system prompt for this group. */
diff --git a/src/config/zod-schema.providers-whatsapp.ts b/src/config/zod-schema.providers-whatsapp.ts
@@ -23,6 +23,8 @@ const ToolPolicyBySenderSchema = z.record(z.string(), ToolPolicySchema).optional
 const WhatsAppGroupEntrySchema = z
   .object({
     requireMention: z.boolean().optional(),
+    listenAfterMentionMs: z.number().int().nonnegative().optional(),
+    listenAfterMentionMaxMs: z.number().int().nonnegative().optional(),
     tools: ToolPolicySchema,
     toolsBySender: ToolPolicyBySenderSchema,
     systemPrompt: z.string().optional(),
