@openclaw/whatsapp 2026.5.1-beta.1

package/src/auto-reply/heartbeat-runner.ts

@@ -0,0 +1,330 @@
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import { newConnectionId } from "../reconnect.js";
+import {
+  DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+  HEARTBEAT_TOKEN,
+  appendCronStyleCurrentTimeLine,
+  canonicalizeMainSessionAlias,
+  emitHeartbeatEvent,
+  formatError,
+  getRuntimeConfig,
+  getChildLogger,
+  getReplyFromConfig,
+  hasOutboundReplyContent,
+  loadSessionStore,
+  normalizeMainKey,
+  redactIdentifier,
+  resolveHeartbeatPrompt,
+  resolveHeartbeatReplyPayload,
+  resolveHeartbeatVisibility,
+  resolveIndicatorType,
+  resolveSendableOutboundReplyParts,
+  resolveSessionKey,
+  resolveStorePath,
+  resolveWhatsAppHeartbeatRecipients,
+  sendMessageWhatsApp,
+  stripHeartbeatToken,
+  updateSessionStore,
+  whatsappHeartbeatLog,
+} from "./heartbeat-runner.runtime.js";
+import { getSessionSnapshot } from "./session-snapshot.js";
+
+function resolveDefaultAgentIdFromConfig(cfg: ReturnType<typeof getRuntimeConfig>): string {
+  const agents = cfg.agents?.list ?? [];
+  const chosen = agents.find((agent) => agent?.default)?.id ?? agents[0]?.id ?? "main";
+  return normalizeOptionalLowercaseString(chosen) ?? "main";
+}
+
+export async function runWebHeartbeatOnce(opts: {
+  cfg?: ReturnType<typeof getRuntimeConfig>;
+  to: string;
+  verbose?: boolean;
+  replyResolver?: typeof getReplyFromConfig;
+  sender?: typeof sendMessageWhatsApp;
+  sessionId?: string;
+  overrideBody?: string;
+  dryRun?: boolean;
+}) {
+  const { cfg: cfgOverride, to, verbose = false, sessionId, overrideBody, dryRun = false } = opts;
+  const replyResolver = opts.replyResolver ?? getReplyFromConfig;
+  const sender = opts.sender ?? sendMessageWhatsApp;
+  const runId = newConnectionId();
+  const redactedTo = redactIdentifier(to);
+  const heartbeatLogger = getChildLogger({
+    module: "web-heartbeat",
+    runId,
+    to: redactedTo,
+  });
+
+  const cfg = cfgOverride ?? getRuntimeConfig();
+
+  // Resolve heartbeat visibility settings for WhatsApp
+  const visibility = resolveHeartbeatVisibility({ cfg, channel: "whatsapp" });
+  const heartbeatOkText = HEARTBEAT_TOKEN;
+
+  const maybeSendHeartbeatOk = async (): Promise<boolean> => {
+    if (!visibility.showOk) {
+      return false;
+    }
+    if (dryRun) {
+      whatsappHeartbeatLog.info(`[dry-run] heartbeat ok -> ${redactedTo}`);
+      return false;
+    }
+    const sendResult = await sender(to, heartbeatOkText, { verbose, cfg });
+    heartbeatLogger.info(
+      {
+        to: redactedTo,
+        messageId: sendResult.messageId,
+        chars: heartbeatOkText.length,
+        reason: "heartbeat-ok",
+      },
+      "heartbeat ok sent",
+    );
+    whatsappHeartbeatLog.info(`heartbeat ok sent to ${redactedTo} (id ${sendResult.messageId})`);
+    return true;
+  };
+
+  const sessionCfg = cfg.session;
+  const sessionScope = sessionCfg?.scope ?? "per-sender";
+  const mainKey = normalizeMainKey(sessionCfg?.mainKey);
+  // Canonicalize so the written key matches what read paths produce (#29683).
+  const rawSessionKey = resolveSessionKey(sessionScope, { From: to }, mainKey);
+  const sessionKey = canonicalizeMainSessionAlias({
+    cfg,
+    agentId: resolveDefaultAgentIdFromConfig(cfg),
+    sessionKey: rawSessionKey,
+  });
+  if (sessionId) {
+    const storePath = resolveStorePath(cfg.session?.store);
+    const store = loadSessionStore(storePath);
+    const current = store[sessionKey] ?? {};
+    store[sessionKey] = {
+      ...current,
+      sessionId,
+      updatedAt: Date.now(),
+    };
+    await updateSessionStore(storePath, (nextStore) => {
+      const nextCurrent = nextStore[sessionKey] ?? current;
+      nextStore[sessionKey] = {
+        ...nextCurrent,
+        sessionId,
+        updatedAt: Date.now(),
+      };
+    });
+  }
+  const sessionSnapshot = getSessionSnapshot(cfg, to, true, { sessionKey });
+  if (verbose) {
+    heartbeatLogger.info(
+      {
+        to: redactedTo,
+        sessionKey: sessionSnapshot.key,
+        sessionId: sessionId ?? sessionSnapshot.entry?.sessionId ?? null,
+        sessionFresh: sessionSnapshot.fresh,
+        resetMode: sessionSnapshot.resetPolicy.mode,
+        resetAtHour: sessionSnapshot.resetPolicy.atHour,
+        idleMinutes: sessionSnapshot.resetPolicy.idleMinutes ?? null,
+        dailyResetAt: sessionSnapshot.dailyResetAt ?? null,
+        idleExpiresAt: sessionSnapshot.idleExpiresAt ?? null,
+      },
+      "heartbeat session snapshot",
+    );
+  }
+
+  if (overrideBody && overrideBody.trim().length === 0) {
+    throw new Error("Override body must be non-empty when provided.");
+  }
+
+  try {
+    if (overrideBody) {
+      if (dryRun) {
+        whatsappHeartbeatLog.info(
+          `[dry-run] web send -> ${redactedTo} (${overrideBody.trim().length} chars, manual message)`,
+        );
+        return;
+      }
+      const sendResult = await sender(to, overrideBody, { verbose, cfg });
+      emitHeartbeatEvent({
+        status: "sent",
+        to,
+        preview: overrideBody.slice(0, 160),
+        hasMedia: false,
+        channel: "whatsapp",
+        indicatorType: visibility.useIndicator ? resolveIndicatorType("sent") : undefined,
+      });
+      heartbeatLogger.info(
+        {
+          to: redactedTo,
+          messageId: sendResult.messageId,
+          chars: overrideBody.length,
+          reason: "manual-message",
+        },
+        "manual heartbeat message sent",
+      );
+      whatsappHeartbeatLog.info(
+        `manual heartbeat sent to ${redactedTo} (id ${sendResult.messageId})`,
+      );
+      return;
+    }
+
+    if (!visibility.showAlerts && !visibility.showOk && !visibility.useIndicator) {
+      heartbeatLogger.info({ to: redactedTo, reason: "alerts-disabled" }, "heartbeat skipped");
+      emitHeartbeatEvent({
+        status: "skipped",
+        to,
+        reason: "alerts-disabled",
+        channel: "whatsapp",
+      });
+      return;
+    }
+
+    const replyResult = await replyResolver(
+      {
+        Body: appendCronStyleCurrentTimeLine(
+          resolveHeartbeatPrompt(cfg.agents?.defaults?.heartbeat?.prompt),
+          cfg,
+          Date.now(),
+        ),
+        From: to,
+        To: to,
+        MessageSid: sessionId ?? sessionSnapshot.entry?.sessionId,
+      },
+      { isHeartbeat: true },
+      cfg,
+    );
+    const replyPayload = resolveHeartbeatReplyPayload(replyResult);
+
+    if (!replyPayload || !hasOutboundReplyContent(replyPayload)) {
+      heartbeatLogger.info(
+        {
+          to: redactedTo,
+          reason: "empty-reply",
+          sessionId: sessionSnapshot.entry?.sessionId ?? null,
+        },
+        "heartbeat skipped",
+      );
+      const okSent = await maybeSendHeartbeatOk();
+      emitHeartbeatEvent({
+        status: "ok-empty",
+        to,
+        channel: "whatsapp",
+        silent: !okSent,
+        indicatorType: visibility.useIndicator ? resolveIndicatorType("ok-empty") : undefined,
+      });
+      return;
+    }
+
+    const reply = resolveSendableOutboundReplyParts(replyPayload);
+    const hasMedia = reply.hasMedia;
+    const ackMaxChars = Math.max(
+      0,
+      cfg.agents?.defaults?.heartbeat?.ackMaxChars ?? DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+    );
+    const stripped = stripHeartbeatToken(replyPayload.text, {
+      mode: "heartbeat",
+      maxAckChars: ackMaxChars,
+    });
+    if (stripped.shouldSkip && !hasMedia) {
+      // Don't let heartbeats keep sessions alive: restore previous updatedAt so idle expiry still works.
+      const storePath = resolveStorePath(cfg.session?.store);
+      const store = loadSessionStore(storePath);
+      if (sessionSnapshot.entry && store[sessionSnapshot.key]) {
+        store[sessionSnapshot.key].updatedAt = sessionSnapshot.entry.updatedAt;
+        await updateSessionStore(storePath, (nextStore) => {
+          const nextEntry = nextStore[sessionSnapshot.key];
+          if (!nextEntry) {
+            return;
+          }
+          nextStore[sessionSnapshot.key] = {
+            ...nextEntry,
+            updatedAt: sessionSnapshot.entry.updatedAt,
+          };
+        });
+      }
+
+      heartbeatLogger.info(
+        { to: redactedTo, reason: "heartbeat-token", rawLength: replyPayload.text?.length },
+        "heartbeat skipped",
+      );
+      const okSent = await maybeSendHeartbeatOk();
+      emitHeartbeatEvent({
+        status: "ok-token",
+        to,
+        channel: "whatsapp",
+        silent: !okSent,
+        indicatorType: visibility.useIndicator ? resolveIndicatorType("ok-token") : undefined,
+      });
+      return;
+    }
+
+    if (hasMedia) {
+      heartbeatLogger.warn(
+        { to: redactedTo },
+        "heartbeat reply contained media; sending text only",
+      );
+    }
+
+    const finalText = stripped.text || reply.text;
+
+    // Check if alerts are disabled for WhatsApp
+    if (!visibility.showAlerts) {
+      heartbeatLogger.info({ to: redactedTo, reason: "alerts-disabled" }, "heartbeat skipped");
+      emitHeartbeatEvent({
+        status: "skipped",
+        to,
+        reason: "alerts-disabled",
+        preview: finalText.slice(0, 200),
+        channel: "whatsapp",
+        hasMedia,
+        indicatorType: visibility.useIndicator ? resolveIndicatorType("sent") : undefined,
+      });
+      return;
+    }
+
+    if (dryRun) {
+      heartbeatLogger.info(
+        { to: redactedTo, reason: "dry-run", chars: finalText.length },
+        "heartbeat dry-run",
+      );
+      whatsappHeartbeatLog.info(`[dry-run] heartbeat -> ${redactedTo} (${finalText.length} chars)`);
+      return;
+    }
+
+    const sendResult = await sender(to, finalText, { verbose, cfg });
+    emitHeartbeatEvent({
+      status: "sent",
+      to,
+      preview: finalText.slice(0, 160),
+      hasMedia,
+      channel: "whatsapp",
+      indicatorType: visibility.useIndicator ? resolveIndicatorType("sent") : undefined,
+    });
+    heartbeatLogger.info(
+      {
+        to: redactedTo,
+        messageId: sendResult.messageId,
+        chars: finalText.length,
+      },
+      "heartbeat sent",
+    );
+    whatsappHeartbeatLog.info(`heartbeat alert sent to ${redactedTo}`);
+  } catch (err) {
+    const reason = formatError(err);
+    heartbeatLogger.warn({ to: redactedTo, error: reason }, "heartbeat failed");
+    whatsappHeartbeatLog.warn(`heartbeat failed (${reason})`);
+    emitHeartbeatEvent({
+      status: "failed",
+      to,
+      reason,
+      channel: "whatsapp",
+      indicatorType: visibility.useIndicator ? resolveIndicatorType("failed") : undefined,
+    });
+    throw err;
+  }
+}
+
+export function resolveHeartbeatRecipients(
+  cfg: ReturnType<typeof getRuntimeConfig>,
+  opts: { to?: string; all?: boolean; accountId?: string } = {},
+) {
+  return resolveWhatsAppHeartbeatRecipients(cfg, opts);
+}

package/src/auto-reply/loggers.ts

@@ -0,0 +1,6 @@
+import { createSubsystemLogger } from "openclaw/plugin-sdk/runtime-env";
+
+export const whatsappLog = createSubsystemLogger("gateway/channels/whatsapp");
+export const whatsappInboundLog = whatsappLog.child("inbound");
+export const whatsappOutboundLog = whatsappLog.child("outbound");
+export const whatsappHeartbeatLog = whatsappLog.child("heartbeat");

package/src/auto-reply/mentions.ts

@@ -0,0 +1,131 @@
+import {
+  buildMentionRegexes,
+  normalizeMentionText,
+} from "openclaw/plugin-sdk/channel-mention-gating";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  getComparableIdentityValues,
+  getMentionIdentities,
+  getSelfIdentity,
+  identitiesOverlap,
+  type WhatsAppIdentity,
+} from "../identity.js";
+import { isWhatsAppGroupJid } from "../normalize-target.js";
+import { isSelfChatMode, normalizeE164 } from "../text-runtime.js";
+import type { WebInboundMsg } from "./types.js";
+
+export type MentionConfig = {
+  mentionRegexes: RegExp[];
+  allowFrom?: Array<string | number>;
+  isSelfChat?: boolean;
+};
+
+export type MentionTargets = {
+  normalizedMentions: WhatsAppIdentity[];
+  self: WhatsAppIdentity;
+};
+
+export function buildMentionConfig(cfg: OpenClawConfig, agentId?: string): MentionConfig {
+  const mentionRegexes = buildMentionRegexes(cfg, agentId);
+  return { mentionRegexes, allowFrom: cfg.channels?.whatsapp?.allowFrom };
+}
+
+export function resolveMentionTargets(msg: WebInboundMsg, authDir?: string): MentionTargets {
+  const normalizedMentions = getMentionIdentities(msg, authDir);
+  const self = getSelfIdentity(msg, authDir);
+  return { normalizedMentions, self };
+}
+
+export function isBotMentionedFromTargets(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  targets: MentionTargets,
+): boolean {
+  const clean = (text: string) =>
+    // Remove zero-width and directionality markers WhatsApp injects around display names
+    normalizeMentionText(text);
+
+  const explicitSelfChatOverride = typeof mentionCfg.isSelfChat === "boolean";
+  // `isSelfChatMode` is a config-shaped check ("is the bot's own E.164 in
+  // allowFrom?"), not a conversation-shaped check, so it returns true even
+  // for group conversations whenever the operator put their own number in
+  // allowFrom — which is the common config. The original mention-skip path
+  // was designed to prevent owner-mentioning-self in a true 1:1 self DM
+  // from falsely triggering the bot, so when we derive the flag implicitly
+  // from `allowFrom`, confine the suppression to non-group conversations
+  // and let real group @mentions go through the identity-overlap check
+  // (#49317). Explicit `mentionCfg.isSelfChat` overrides from the caller
+  // are honored as-is so multi-account / precomputed paths keep working.
+  const isGroupConversation = isWhatsAppGroupJid(msg.from);
+  const isSelfChat = explicitSelfChatOverride
+    ? Boolean(mentionCfg.isSelfChat)
+    : isSelfChatMode(targets.self.e164, mentionCfg.allowFrom) && !isGroupConversation;
+
+  const hasMentions = targets.normalizedMentions.length > 0;
+  if (hasMentions && !isSelfChat) {
+    for (const mention of targets.normalizedMentions) {
+      if (identitiesOverlap(targets.self, mention)) {
+        return true;
+      }
+    }
+    // If the message explicitly mentions someone else, do not fall back to regex matches.
+    return false;
+  } else if (hasMentions && isSelfChat) {
+    // Self-chat mode: ignore WhatsApp @mention JIDs, otherwise @mentioning the owner in self-chat triggers the bot.
+  }
+  const bodyClean = clean(msg.body);
+  if (mentionCfg.mentionRegexes.some((re) => re.test(bodyClean))) {
+    return true;
+  }
+
+  // Fallback: detect body containing our own number (with or without +, spacing)
+  if (targets.self.e164) {
+    const selfDigits = targets.self.e164.replace(/\D/g, "");
+    if (selfDigits) {
+      const bodyDigits = bodyClean.replace(/[^\d]/g, "");
+      if (bodyDigits.includes(selfDigits)) {
+        return true;
+      }
+      const bodyNoSpace = msg.body.replace(/[\s-]/g, "");
+      const pattern = new RegExp(`\\+?${selfDigits}`, "i");
+      if (pattern.test(bodyNoSpace)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function debugMention(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  authDir?: string,
+): { wasMentioned: boolean; details: Record<string, unknown> } {
+  const mentionTargets = resolveMentionTargets(msg, authDir);
+  const result = isBotMentionedFromTargets(msg, mentionCfg, mentionTargets);
+  const details = {
+    from: msg.from,
+    body: msg.body,
+    bodyClean: normalizeMentionText(msg.body),
+    mentionedJids: msg.mentions ?? msg.mentionedJids ?? null,
+    normalizedMentionedJids: mentionTargets.normalizedMentions.length
+      ? mentionTargets.normalizedMentions.map((identity) => getComparableIdentityValues(identity))
+      : null,
+    selfJid: msg.self?.jid ?? msg.selfJid ?? null,
+    selfLid: msg.self?.lid ?? msg.selfLid ?? null,
+    selfE164: msg.self?.e164 ?? msg.selfE164 ?? null,
+    resolvedSelf: mentionTargets.self,
+  };
+  return { wasMentioned: result, details };
+}
+
+export function resolveOwnerList(mentionCfg: MentionConfig, selfE164?: string | null) {
+  const allowFrom = mentionCfg.allowFrom;
+  const raw =
+    Array.isArray(allowFrom) && allowFrom.length > 0 ? allowFrom : selfE164 ? [selfE164] : [];
+  return raw
+    .filter((entry): entry is string => Boolean(entry && entry !== "*"))
+    .map((entry) => normalizeE164(entry))
+    .filter((entry): entry is string => Boolean(entry));
+}

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

@@ -0,0 +1,170 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { WhatsAppSendResult } from "../../inbound/send-result.js";
+import type { WebInboundMessage } from "../../inbound/types.js";
+import { maybeSendAckReaction } from "./ack-reaction.js";
+
+const hoisted = vi.hoisted(() => ({
+  sendReactionWhatsApp: vi.fn(async () => undefined),
+}));
+
+vi.mock("../../send.js", () => ({
+  sendReactionWhatsApp: hoisted.sendReactionWhatsApp,
+}));
+
+function acceptedSendResult(kind: "media" | "text", id: string): WhatsAppSendResult {
+  return {
+    kind,
+    messageId: id,
+    messageIds: [id],
+    keys: [{ id }],
+    providerAccepted: true,
+  };
+}
+
+function createMessage(overrides: Partial<WebInboundMessage> = {}): WebInboundMessage {
+  return {
+    id: "msg-1",
+    from: "15551234567",
+    conversationId: "15551234567",
+    to: "15559876543",
+    accountId: "default",
+    body: "hello",
+    chatType: "direct",
+    chatId: "15551234567@s.whatsapp.net",
+    sendComposing: async () => {},
+    reply: async () => acceptedSendResult("text", "r1"),
+    sendMedia: async () => acceptedSendResult("media", "m1"),
+    ...overrides,
+  };
+}
+
+function createConfig(
+  reactionLevel: "off" | "ack" | "minimal" | "extensive",
+  extras?: Partial<NonNullable<OpenClawConfig["channels"]>["whatsapp"]>,
+): OpenClawConfig {
+  return {
+    channels: {
+      whatsapp: {
+        reactionLevel,
+        ackReaction: {
+          emoji: "👀",
+          direct: true,
+          group: "mentions",
+        },
+        ...extras,
+      },
+    },
+  } as OpenClawConfig;
+}
+
+type AckReactionParams = Parameters<typeof maybeSendAckReaction>[0];
+
+const runAckReaction = (overrides: Partial<AckReactionParams> = {}) =>
+  maybeSendAckReaction({
+    cfg: createConfig("ack"),
+    msg: createMessage(),
+    agentId: "agent",
+    sessionKey: "whatsapp:default:15551234567",
+    conversationId: "15551234567",
+    verbose: false,
+    accountId: "default",
+    info: vi.fn(),
+    warn: vi.fn(),
+    ...overrides,
+  });
+
+const expectAckReactionSent = (accountId: string) => {
+  expect(hoisted.sendReactionWhatsApp).toHaveBeenCalledWith(
+    "15551234567@s.whatsapp.net",
+    "msg-1",
+    "👀",
+    expect.objectContaining({
+      verbose: false,
+      fromMe: false,
+      accountId,
+    }),
+  );
+};
+
+describe("maybeSendAckReaction", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it.each(["ack", "minimal", "extensive"] as const)(
+    "sends ack reactions when reactionLevel is %s",
+    async (reactionLevel) => {
+      const ackReaction = await runAckReaction({
+        cfg: createConfig(reactionLevel),
+      });
+
+      expect(ackReaction?.ackReactionValue).toBe("👀");
+      await expect(ackReaction?.ackReactionPromise).resolves.toBe(true);
+      expectAckReactionSent("default");
+    },
+  );
+
+  it("suppresses ack reactions when reactionLevel is off", async () => {
+    const ackReaction = await runAckReaction({
+      cfg: createConfig("off"),
+    });
+
+    expect(ackReaction).toBeNull();
+    expect(hoisted.sendReactionWhatsApp).not.toHaveBeenCalled();
+  });
+
+  it("uses the active account reactionLevel override for ack gating", async () => {
+    const ackReaction = await runAckReaction({
+      cfg: createConfig("off", {
+        accounts: {
+          work: {
+            reactionLevel: "ack",
+          },
+        },
+      }),
+      msg: createMessage({
+        accountId: "work",
+      }),
+      sessionKey: "whatsapp:work:15551234567",
+      accountId: "work",
+    });
+
+    expect(ackReaction?.ackReactionValue).toBe("👀");
+    expectAckReactionSent("work");
+  });
+
+  it("returns a handle that removes the ack with an empty reaction", async () => {
+    const ackReaction = await runAckReaction();
+
+    await ackReaction?.remove();
+
+    expect(hoisted.sendReactionWhatsApp).toHaveBeenLastCalledWith(
+      "15551234567@s.whatsapp.net",
+      "msg-1",
+      "",
+      expect.objectContaining({
+        verbose: false,
+        fromMe: false,
+        accountId: "default",
+      }),
+    );
+  });
+
+  it("records ack send failures on the handle", async () => {
+    const warn = vi.fn();
+    hoisted.sendReactionWhatsApp.mockRejectedValueOnce(new Error("session down"));
+
+    const ackReaction = await runAckReaction({ warn });
+
+    await expect(ackReaction?.ackReactionPromise).resolves.toBe(false);
+    expect(warn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: "session down",
+        chatId: "15551234567@s.whatsapp.net",
+        messageId: "msg-1",
+      }),
+      "failed to send ack reaction",
+    );
+  });
+});