@openclaw/whatsapp 2026.5.1-beta.1

package/src/quoted-message.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import {
+  cacheInboundMessageMeta,
+  lookupInboundMessageMeta,
+  lookupInboundMessageMetaForTarget,
+} from "./quoted-message.js";
+
+describe("quoted message metadata cache", () => {
+  it("scopes cached metadata by account id", () => {
+    cacheInboundMessageMeta("account-a", "1555@s.whatsapp.net", "msg-1", {
+      participant: "111@s.whatsapp.net",
+      body: "hello from a",
+      fromMe: true,
+    });
+    cacheInboundMessageMeta("account-b", "1555@s.whatsapp.net", "msg-1", {
+      participant: "222@s.whatsapp.net",
+      body: "hello from b",
+      fromMe: false,
+    });
+
+    expect(lookupInboundMessageMeta("account-a", "1555@s.whatsapp.net", "msg-1")).toEqual({
+      participant: "111@s.whatsapp.net",
+      body: "hello from a",
+      fromMe: true,
+    });
+    expect(lookupInboundMessageMeta("account-b", "1555@s.whatsapp.net", "msg-1")).toEqual({
+      participant: "222@s.whatsapp.net",
+      body: "hello from b",
+      fromMe: false,
+    });
+  });
+
+  it("can recover the original remoteJid for a matching direct-chat target", () => {
+    cacheInboundMessageMeta("account-c", "277038292303944@lid", "msg-2", {
+      participant: "5511976136970@s.whatsapp.net",
+      body: "hello from lid chat",
+      fromMe: true,
+    });
+
+    expect(
+      lookupInboundMessageMetaForTarget("account-c", "5511976136970@s.whatsapp.net", "msg-2"),
+    ).toEqual({
+      remoteJid: "277038292303944@lid",
+      participant: "5511976136970@s.whatsapp.net",
+      body: "hello from lid chat",
+      fromMe: true,
+    });
+    expect(
+      lookupInboundMessageMetaForTarget("account-c", "99999999999@s.whatsapp.net", "msg-2"),
+    ).toBeUndefined();
+    expect(
+      lookupInboundMessageMetaForTarget("missing", "5511976136970@s.whatsapp.net", "msg-2"),
+    ).toBeUndefined();
+  });
+
+  it("can recover a direct-chat remoteJid when only sender E164 was cached", () => {
+    cacheInboundMessageMeta("account-e", "277038292303944@lid", "msg-4", {
+      participantE164: "+5511976136970",
+      body: "hello from e164 participant",
+    });
+
+    expect(
+      lookupInboundMessageMetaForTarget("account-e", "5511976136970@s.whatsapp.net", "msg-4"),
+    ).toEqual({
+      remoteJid: "277038292303944@lid",
+      participant: undefined,
+      participantE164: "+5511976136970",
+      body: "hello from e164 participant",
+      fromMe: undefined,
+    });
+  });
+
+  it("does not recover metadata from another chat when the target conversation differs", () => {
+    cacheInboundMessageMeta("account-d", "120363400000000000@g.us", "msg-3", {
+      participant: "111@s.whatsapp.net",
+      body: "group secret",
+    });
+
+    expect(
+      lookupInboundMessageMetaForTarget("account-d", "222@s.whatsapp.net", "msg-3"),
+    ).toBeUndefined();
+  });
+});

package/src/quoted-message.ts

@@ -0,0 +1,184 @@
+import type { MiscMessageGenerationOptions } from "@whiskeysockets/baileys";
+import { jidToE164 } from "./text-runtime.js";
+
+// ── Inbound message metadata cache ──────────────────────────────────────
+// Maps messageId → { participant, participantE164, body, fromMe } so the
+// outbound adapter can
+// populate the quote key with the sender JID and preview text even though
+// the outbound path only receives a bare messageId string.
+
+type QuotedMeta = {
+  participant?: string;
+  participantE164?: string;
+  body?: string;
+  fromMe?: boolean;
+};
+type CacheEntry = QuotedMeta & { ts: number };
+type QuotedMetaLookup = QuotedMeta & { remoteJid: string };
+
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const MAX_ENTRIES = 500;
+const cache = new Map<string, CacheEntry>();
+
+function makeCacheKey(accountId: string, remoteJid: string, messageId: string): string {
+  return `${accountId}:${remoteJid}:${messageId}`;
+}
+
+export function cacheInboundMessageMeta(
+  accountId: string,
+  remoteJid: string,
+  messageId: string,
+  meta: QuotedMeta,
+): void {
+  if (!accountId || !messageId || !remoteJid) {
+    return;
+  }
+  if (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest) {
+      cache.delete(oldest);
+    }
+  }
+  cache.set(makeCacheKey(accountId, remoteJid, messageId), { ...meta, ts: Date.now() });
+}
+
+export function lookupInboundMessageMeta(
+  accountId: string,
+  remoteJid: string,
+  messageId: string,
+): QuotedMeta | undefined {
+  const cacheKey = makeCacheKey(accountId, remoteJid, messageId);
+  const entry = cache.get(cacheKey);
+  if (!entry) {
+    return undefined;
+  }
+  if (Date.now() - entry.ts > CACHE_TTL_MS) {
+    cache.delete(cacheKey);
+    return undefined;
+  }
+  return {
+    participant: entry.participant,
+    participantE164: entry.participantE164,
+    body: entry.body,
+    fromMe: entry.fromMe,
+  };
+}
+
+function normalizeComparableJid(jid: string | undefined): string | undefined {
+  const normalized = jid?.trim().replace(/:\d+/, "").toLowerCase();
+  return normalized || undefined;
+}
+
+function isGroupJid(jid: string | undefined): boolean {
+  return Boolean(jid && jid.endsWith("@g.us"));
+}
+
+function areComparableE164sEqual(left: string | undefined, right: string | undefined): boolean {
+  const normalizedLeft = left?.trim();
+  const normalizedRight = right?.trim();
+  if (!normalizedLeft || !normalizedRight) {
+    return false;
+  }
+  return normalizedLeft === normalizedRight;
+}
+
+function areComparableJidsEqual(left: string | undefined, right: string | undefined): boolean {
+  const normalizedLeft = normalizeComparableJid(left);
+  const normalizedRight = normalizeComparableJid(right);
+  if (!normalizedLeft || !normalizedRight) {
+    return false;
+  }
+  if (normalizedLeft === normalizedRight) {
+    return true;
+  }
+  const leftE164 = jidToE164(normalizedLeft);
+  const rightE164 = jidToE164(normalizedRight);
+  return Boolean(leftE164 && rightE164 && leftE164 === rightE164);
+}
+
+function matchesQuotedConversationTarget(targetJid: string, candidate: QuotedMetaLookup): boolean {
+  if (areComparableJidsEqual(targetJid, candidate.remoteJid)) {
+    return true;
+  }
+  if (isGroupJid(targetJid) || isGroupJid(candidate.remoteJid)) {
+    return false;
+  }
+  return (
+    areComparableJidsEqual(targetJid, candidate.participant) ||
+    areComparableE164sEqual(jidToE164(targetJid) ?? undefined, candidate.participantE164)
+  );
+}
+
+export function lookupInboundMessageMetaForTarget(
+  accountId: string,
+  targetJid: string,
+  messageId: string,
+): QuotedMetaLookup | undefined {
+  if (!accountId || !messageId || !targetJid) {
+    return undefined;
+  }
+  const exact = lookupInboundMessageMeta(accountId, targetJid, messageId);
+  if (exact) {
+    return {
+      remoteJid: targetJid,
+      participant: exact.participant,
+      participantE164: exact.participantE164,
+      body: exact.body,
+      fromMe: exact.fromMe,
+    };
+  }
+  const prefix = `${accountId}:`;
+  const suffix = `:${messageId}`;
+  let matched: QuotedMetaLookup | undefined;
+  for (const [cacheKey, entry] of cache.entries()) {
+    if (!cacheKey.startsWith(prefix) || !cacheKey.endsWith(suffix)) {
+      continue;
+    }
+    if (Date.now() - entry.ts > CACHE_TTL_MS) {
+      cache.delete(cacheKey);
+      continue;
+    }
+    const remoteJid = cacheKey.slice(prefix.length, cacheKey.length - suffix.length);
+    const candidate = {
+      remoteJid,
+      participant: entry.participant,
+      participantE164: entry.participantE164,
+      body: entry.body,
+      fromMe: entry.fromMe,
+    };
+    if (!matchesQuotedConversationTarget(targetJid, candidate)) {
+      continue;
+    }
+    if (matched) {
+      return undefined;
+    }
+    matched = candidate;
+  }
+  return matched;
+}
+
+export function buildQuotedMessageOptions(params: {
+  messageId?: string | null;
+  remoteJid?: string | null;
+  fromMe?: boolean;
+  participant?: string;
+  /** Original message text — shown in the quote preview bubble. */
+  messageText?: string;
+}): MiscMessageGenerationOptions | undefined {
+  const id = params.messageId?.trim();
+  const remoteJid = params.remoteJid?.trim();
+  if (!id || !remoteJid) {
+    return undefined;
+  }
+  return {
+    quoted: {
+      key: {
+        remoteJid,
+        id,
+        fromMe: params.fromMe ?? false,
+        participant: params.participant,
+      },
+      message: { conversation: params.messageText ?? "" },
+    },
+  } as MiscMessageGenerationOptions;
+}

package/src/reaction-level.test.ts

@@ -0,0 +1,94 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { describe, expect, it } from "vitest";
+import { resolveWhatsAppReactionLevel } from "./reaction-level.js";
+
+describe("resolveWhatsAppReactionLevel", () => {
+  it("defaults to minimal level when reactionLevel is not set", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: {} },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg });
+    expect(result).toEqual({
+      level: "minimal",
+      ackEnabled: false,
+      agentReactionsEnabled: true,
+      agentReactionGuidance: "minimal",
+    });
+  });
+
+  it("returns off level with no reactions enabled", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: { reactionLevel: "off" } },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg });
+    expect(result).toEqual({
+      level: "off",
+      ackEnabled: false,
+      agentReactionsEnabled: false,
+    });
+  });
+
+  it("returns ack level with only ackEnabled", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: { reactionLevel: "ack" } },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg });
+    expect(result).toEqual({
+      level: "ack",
+      ackEnabled: true,
+      agentReactionsEnabled: false,
+    });
+  });
+
+  it("returns minimal level with agent reactions enabled and minimal guidance", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: { reactionLevel: "minimal" } },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg });
+    expect(result).toEqual({
+      level: "minimal",
+      ackEnabled: false,
+      agentReactionsEnabled: true,
+      agentReactionGuidance: "minimal",
+    });
+  });
+
+  it("returns extensive level with agent reactions enabled and extensive guidance", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: { reactionLevel: "extensive" } },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg });
+    expect(result).toEqual({
+      level: "extensive",
+      ackEnabled: false,
+      agentReactionsEnabled: true,
+      agentReactionGuidance: "extensive",
+    });
+  });
+
+  it("resolves reaction level from a specific account", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        whatsapp: {
+          reactionLevel: "minimal",
+          accounts: {
+            work: { reactionLevel: "extensive" },
+          },
+        },
+      },
+    };
+
+    const result = resolveWhatsAppReactionLevel({ cfg, accountId: "work" });
+    expect(result).toEqual({
+      level: "extensive",
+      ackEnabled: false,
+      agentReactionsEnabled: true,
+      agentReactionGuidance: "extensive",
+    });
+  });
+});

package/src/reaction-level.ts

@@ -0,0 +1,21 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveReactionLevel, type ResolvedReactionLevel } from "openclaw/plugin-sdk/text-runtime";
+import { resolveMergedWhatsAppAccountConfig } from "./account-config.js";
+
+type ResolvedWhatsAppReactionLevel = ResolvedReactionLevel;
+
+/** Resolve the effective reaction level and its implications for WhatsApp. */
+export function resolveWhatsAppReactionLevel(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): ResolvedWhatsAppReactionLevel {
+  const account = resolveMergedWhatsAppAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  return resolveReactionLevel({
+    value: account.reactionLevel,
+    defaultLevel: "minimal",
+    invalidFallback: "minimal",
+  });
+}

package/src/reconnect.test.ts

@@ -0,0 +1,51 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { describe, expect, it } from "vitest";
+import {
+  computeBackoff,
+  DEFAULT_HEARTBEAT_SECONDS,
+  DEFAULT_RECONNECT_POLICY,
+  resolveHeartbeatSeconds,
+  resolveReconnectPolicy,
+  sleepWithAbort,
+} from "./reconnect.js";
+
+describe("web reconnect helpers", () => {
+  const cfg: OpenClawConfig = {};
+
+  it("resolves sane reconnect defaults with clamps", () => {
+    const policy = resolveReconnectPolicy(cfg, {
+      initialMs: 100,
+      maxMs: 5,
+      factor: 20,
+      jitter: 2,
+      maxAttempts: -1,
+    });
+
+    expect(policy.initialMs).toBe(250); // clamped to minimum
+    expect(policy.maxMs).toBeGreaterThanOrEqual(policy.initialMs);
+    expect(policy.factor).toBeLessThanOrEqual(10);
+    expect(policy.jitter).toBeLessThanOrEqual(1);
+    expect(policy.maxAttempts).toBeGreaterThanOrEqual(0);
+  });
+
+  it("computes increasing backoff with jitter", () => {
+    const policy = { ...DEFAULT_RECONNECT_POLICY, jitter: 0 };
+    const first = computeBackoff(policy, 1);
+    const second = computeBackoff(policy, 2);
+    expect(first).toBe(policy.initialMs);
+    expect(second).toBeGreaterThan(first);
+    expect(second).toBeLessThanOrEqual(policy.maxMs);
+  });
+
+  it("returns heartbeat default when unset", () => {
+    expect(resolveHeartbeatSeconds(cfg)).toBe(DEFAULT_HEARTBEAT_SECONDS);
+    expect(resolveHeartbeatSeconds(cfg, 5)).toBe(5);
+  });
+
+  it("sleepWithAbort rejects on abort", async () => {
+    const controller = new AbortController();
+    const promise = sleepWithAbort(50, controller.signal);
+    controller.abort();
+    await expect(promise).rejects.toThrow("aborted");
+  });
+});

package/src/reconnect.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  computeBackoff,
+  sleepWithAbort,
+  type BackoffPolicy,
+} from "openclaw/plugin-sdk/runtime-env";
+import { clamp } from "openclaw/plugin-sdk/text-runtime";
+
+export type ReconnectPolicy = BackoffPolicy & {
+  maxAttempts: number;
+};
+
+export const DEFAULT_HEARTBEAT_SECONDS = 60;
+export const DEFAULT_RECONNECT_POLICY: ReconnectPolicy = {
+  initialMs: 2_000,
+  maxMs: 30_000,
+  factor: 1.8,
+  jitter: 0.25,
+  maxAttempts: 12,
+};
+
+export function resolveHeartbeatSeconds(cfg: OpenClawConfig, overrideSeconds?: number): number {
+  const candidate = overrideSeconds ?? cfg.web?.heartbeatSeconds;
+  if (typeof candidate === "number" && candidate > 0) {
+    return candidate;
+  }
+  return DEFAULT_HEARTBEAT_SECONDS;
+}
+
+export function resolveReconnectPolicy(
+  cfg: OpenClawConfig,
+  overrides?: Partial<ReconnectPolicy>,
+): ReconnectPolicy {
+  const reconnectOverrides = cfg.web?.reconnect ?? {};
+  const overrideConfig = overrides ?? {};
+  const merged = {
+    ...DEFAULT_RECONNECT_POLICY,
+    ...reconnectOverrides,
+    ...overrideConfig,
+  } as ReconnectPolicy;
+
+  merged.initialMs = Math.max(250, merged.initialMs);
+  merged.maxMs = Math.max(merged.initialMs, merged.maxMs);
+  merged.factor = clamp(merged.factor, 1.1, 10);
+  merged.jitter = clamp(merged.jitter, 0, 1);
+  merged.maxAttempts = Math.max(0, Math.floor(merged.maxAttempts));
+  return merged;
+}
+
+export { computeBackoff, sleepWithAbort };
+
+export function newConnectionId() {
+  return randomUUID();
+}