@openclaw/whatsapp 2026.5.1-beta.1

package/src/creds-persistence.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveWebCredsPath } from "./creds-files.js";
+
+const CREDS_FILE_MODE = 0o600;
+const CREDS_SAVE_FLUSH_TIMEOUT_MS = 15_000;
+
+const credsSaveQueues = new Map<string, Promise<void>>();
+
+export type CredsQueueWaitResult = "drained" | "timed_out";
+
+async function stringifyCreds(creds: unknown): Promise<string> {
+  const { BufferJSON } = await import("./session.runtime.js");
+  return JSON.stringify(creds, BufferJSON.replacer);
+}
+
+async function syncDirectory(dirPath: string): Promise<void> {
+  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
+  try {
+    handle = await fs.open(dirPath, "r");
+    await handle.sync();
+  } catch {
+    // best-effort on platforms that do not support directory fsync
+  } finally {
+    await handle?.close().catch(() => {
+      // best-effort close
+    });
+  }
+}
+
+export async function writeCredsJsonAtomically(authDir: string, creds: unknown): Promise<void> {
+  const credsPath = resolveWebCredsPath(authDir);
+  const tempPath = path.join(authDir, `.creds.${process.pid}.${randomUUID()}.tmp`);
+  const json = await stringifyCreds(creds);
+
+  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
+  try {
+    handle = await fs.open(tempPath, "w", CREDS_FILE_MODE);
+    await handle.writeFile(json, { encoding: "utf-8" });
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+
+    await fs.rename(tempPath, credsPath);
+    await fs.chmod(credsPath, CREDS_FILE_MODE).catch(() => {
+      // best-effort on platforms that support it
+    });
+    await syncDirectory(path.dirname(credsPath));
+  } catch (error) {
+    await handle?.close().catch(() => {
+      // best-effort close
+    });
+    await fs.rm(tempPath, { force: true }).catch(() => {
+      // best-effort cleanup
+    });
+    throw error;
+  }
+}
+
+export function enqueueCredsSave(
+  authDir: string,
+  saveCreds: () => Promise<void> | void,
+  onError: (error: unknown) => void,
+): void {
+  const previous = credsSaveQueues.get(authDir) ?? Promise.resolve();
+  const next = previous
+    .then(() => saveCreds())
+    .catch((error) => {
+      onError(error);
+    })
+    .finally(() => {
+      if (credsSaveQueues.get(authDir) === next) {
+        credsSaveQueues.delete(authDir);
+      }
+    });
+  credsSaveQueues.set(authDir, next);
+}
+
+export function waitForCredsSaveQueue(authDir?: string): Promise<void> {
+  if (authDir) {
+    return credsSaveQueues.get(authDir) ?? Promise.resolve();
+  }
+  return Promise.all(credsSaveQueues.values()).then(() => {});
+}
+
+export async function waitForCredsSaveQueueWithTimeout(
+  authDir: string,
+  timeoutMs = CREDS_SAVE_FLUSH_TIMEOUT_MS,
+): Promise<CredsQueueWaitResult> {
+  let flushTimeout: ReturnType<typeof setTimeout> | undefined;
+  return await Promise.race([
+    waitForCredsSaveQueue(authDir).then(() => "drained" as const),
+    new Promise<CredsQueueWaitResult>((resolve) => {
+      flushTimeout = setTimeout(() => resolve("timed_out"), timeoutMs);
+    }),
+  ]).finally(() => {
+    if (flushTimeout) {
+      clearTimeout(flushTimeout);
+    }
+  });
+}

package/src/directory-config.test.ts

@@ -0,0 +1,60 @@
+import { createDirectoryTestRuntime } from "openclaw/plugin-sdk/channel-test-helpers";
+import { describe, expect, it } from "vitest";
+import {
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "./directory-config.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+
+describe("whatsapp directory", () => {
+  const runtimeEnv = createDirectoryTestRuntime() as never;
+
+  it("lists peers and groups from config", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          authDir: "/tmp/wa-auth",
+          allowFrom: [
+            "whatsapp:+15551230001",
+            "15551230002@s.whatsapp.net",
+            "120363999999999999@g.us",
+          ],
+          groups: {
+            "120363111111111111@g.us": {},
+            "120363222222222222@g.us": {},
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    await expect(
+      listWhatsAppDirectoryPeersFromConfig({
+        cfg,
+        accountId: undefined,
+        query: undefined,
+        limit: undefined,
+        runtime: runtimeEnv,
+      } as never),
+    ).resolves.toEqual(
+      expect.arrayContaining([
+        { kind: "user", id: "+15551230001" },
+        { kind: "user", id: "+15551230002" },
+      ]),
+    );
+
+    await expect(
+      listWhatsAppDirectoryGroupsFromConfig({
+        cfg,
+        accountId: undefined,
+        query: undefined,
+        limit: undefined,
+        runtime: runtimeEnv,
+      } as never),
+    ).resolves.toEqual(
+      expect.arrayContaining([
+        { kind: "group", id: "120363111111111111@g.us" },
+        { kind: "group", id: "120363222222222222@g.us" },
+      ]),
+    );
+  });
+});

package/src/directory-config.ts

@@ -0,0 +1,40 @@
+import {
+  listResolvedDirectoryGroupEntriesFromMapKeys,
+  listResolvedDirectoryUserEntriesFromAllowFrom,
+  type DirectoryConfigParams,
+} from "openclaw/plugin-sdk/directory-config-runtime";
+import { resolveMergedWhatsAppAccountConfig } from "./account-config.js";
+import type { WhatsAppAccountConfig } from "./account-types.js";
+import { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "./normalize.js";
+
+type WhatsAppDirectoryAccount = WhatsAppAccountConfig & { accountId: string };
+
+function resolveWhatsAppDirectoryAccount(
+  cfg: DirectoryConfigParams["cfg"],
+  accountId?: string | null,
+): WhatsAppDirectoryAccount {
+  return resolveMergedWhatsAppAccountConfig({ cfg, accountId });
+}
+
+export async function listWhatsAppDirectoryPeersFromConfig(params: DirectoryConfigParams) {
+  return listResolvedDirectoryUserEntriesFromAllowFrom<WhatsAppDirectoryAccount>({
+    ...params,
+    resolveAccount: resolveWhatsAppDirectoryAccount,
+    resolveAllowFrom: (account) => account.allowFrom,
+    normalizeId: (entry) => {
+      const normalized = normalizeWhatsAppTarget(entry);
+      if (!normalized || isWhatsAppGroupJid(normalized)) {
+        return null;
+      }
+      return normalized;
+    },
+  });
+}
+
+export async function listWhatsAppDirectoryGroupsFromConfig(params: DirectoryConfigParams) {
+  return listResolvedDirectoryGroupEntriesFromMapKeys<WhatsAppDirectoryAccount>({
+    ...params,
+    resolveAccount: resolveWhatsAppDirectoryAccount,
+    resolveGroups: (account) => account.groups,
+  });
+}

package/src/directory-contract.test.ts

@@ -0,0 +1,56 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { describe, expect, it } from "vitest";
+import {
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "../directory-contract-api.js";
+
+function ids(entries: Array<{ id: string }>) {
+  return entries.map((entry) => entry.id);
+}
+
+describe("WhatsApp directory contract", () => {
+  it("lists peers/groups from config", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          allowFrom: ["+15550000000", "*", "123@g.us"],
+          groups: { "999@g.us": { requireMention: true }, "*": {} },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const peers = await listWhatsAppDirectoryPeersFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    const groups = await listWhatsAppDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(ids(peers)).toEqual(["+15550000000"]);
+    expect(ids(groups)).toEqual(["999@g.us"]);
+  });
+
+  it("applies query and limit filtering for config-backed directories", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          groups: { "111@g.us": {}, "222@g.us": {}, "333@s.whatsapp.net": {} },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const groups = await listWhatsAppDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: "@g.us",
+      limit: 1,
+    });
+    expect(ids(groups)).toEqual(["111@g.us"]);
+  });
+});

package/src/doctor-contract.ts

@@ -0,0 +1,11 @@
+import type { ChannelDoctorConfigMutation } from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { normalizeCompatibilityConfig as normalizeCompatibilityConfigImpl } from "./doctor.js";
+
+export function normalizeCompatibilityConfig({
+  cfg,
+}: {
+  cfg: OpenClawConfig;
+}): ChannelDoctorConfigMutation {
+  return normalizeCompatibilityConfigImpl({ cfg });
+}

package/src/doctor.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { normalizeCompatibilityConfig } from "./doctor.js";
+
+describe("whatsapp doctor compatibility", () => {
+  it("does not add whatsapp config when the channel is not configured", () => {
+    const result = normalizeCompatibilityConfig({
+      cfg: {
+        messages: {
+          ackReaction: "👀",
+          ackReactionScope: "group-mentions",
+        },
+      },
+    });
+
+    expect(result.config.channels?.whatsapp).toBeUndefined();
+    expect(result.changes).toEqual([]);
+  });
+
+  it("copies legacy ack reaction into configured whatsapp channel", () => {
+    const result = normalizeCompatibilityConfig({
+      cfg: {
+        messages: {
+          ackReaction: "👀",
+          ackReactionScope: "group-mentions",
+        },
+        channels: {
+          whatsapp: {
+            accounts: {
+              work: {
+                authDir: "/tmp/openclaw-wa-auth",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(result.config.channels?.whatsapp?.ackReaction).toEqual({
+      emoji: "👀",
+      direct: false,
+      group: "mentions",
+    });
+    expect(result.changes).toEqual([
+      "Copied messages.ackReaction → channels.whatsapp.ackReaction (scope: group-mentions).",
+    ]);
+  });
+
+  it("keeps existing whatsapp ack reaction", () => {
+    const result = normalizeCompatibilityConfig({
+      cfg: {
+        messages: {
+          ackReaction: "👀",
+          ackReactionScope: "all",
+        },
+        channels: {
+          whatsapp: {
+            ackReaction: {
+              emoji: "✅",
+              direct: true,
+              group: "always",
+            },
+          },
+        },
+      },
+    });
+
+    expect(result.config.channels?.whatsapp?.ackReaction).toEqual({
+      emoji: "✅",
+      direct: true,
+      group: "always",
+    });
+    expect(result.changes).toEqual([]);
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,56 @@
+import type {
+  ChannelDoctorAdapter,
+  ChannelDoctorConfigMutation,
+} from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export function normalizeCompatibilityConfig({
+  cfg,
+}: {
+  cfg: OpenClawConfig;
+}): ChannelDoctorConfigMutation {
+  const legacyAckReaction = cfg.messages?.ackReaction?.trim();
+  if (!legacyAckReaction || cfg.channels?.whatsapp === undefined) {
+    return { config: cfg, changes: [] };
+  }
+  if (cfg.channels.whatsapp?.ackReaction !== undefined) {
+    return { config: cfg, changes: [] };
+  }
+
+  const legacyScope = cfg.messages?.ackReactionScope ?? "group-mentions";
+  let direct = true;
+  let group: "always" | "mentions" | "never" = "mentions";
+  if (legacyScope === "all") {
+    direct = true;
+    group = "always";
+  } else if (legacyScope === "direct") {
+    direct = true;
+    group = "never";
+  } else if (legacyScope === "group-all") {
+    direct = false;
+    group = "always";
+  } else if (legacyScope === "group-mentions") {
+    direct = false;
+    group = "mentions";
+  }
+
+  return {
+    config: {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        whatsapp: {
+          ...cfg.channels?.whatsapp,
+          ackReaction: { emoji: legacyAckReaction, direct, group },
+        },
+      },
+    },
+    changes: [
+      `Copied messages.ackReaction → channels.whatsapp.ackReaction (scope: ${legacyScope}).`,
+    ],
+  };
+}
+
+export const whatsappDoctor: ChannelDoctorAdapter = {
+  normalizeCompatibilityConfig,
+};

package/src/group-intro.ts

@@ -0,0 +1,15 @@
+const WHATSAPP_GROUP_INTRO_HINT =
+  "WhatsApp IDs: SenderId is the participant JID (group participant id).";
+
+export function resolveWhatsAppGroupIntroHint(): string {
+  return WHATSAPP_GROUP_INTRO_HINT;
+}
+
+export function resolveWhatsAppMentionStripRegexes(ctx: { To?: string | null }): RegExp[] {
+  const selfE164 = (ctx.To ?? "").replace(/^whatsapp:/i, "");
+  if (!selfE164) {
+    return [];
+  }
+  const escaped = selfE164.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return [new RegExp(escaped, "g"), new RegExp(`@${escaped}`, "g")];
+}

package/src/group-policy.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppGroupToolPolicy,
+} from "./group-policy.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+
+describe("whatsapp group policy", () => {
+  it("uses generic channel group policy helpers", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          groups: {
+            "1203630@g.us": {
+              requireMention: false,
+              tools: { deny: ["exec"] },
+            },
+            "*": {
+              requireMention: true,
+              tools: { allow: ["message.send"] },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(resolveWhatsAppGroupRequireMention({ cfg, groupId: "1203630@g.us" })).toBe(false);
+    expect(resolveWhatsAppGroupRequireMention({ cfg, groupId: "other@g.us" })).toBe(true);
+    expect(resolveWhatsAppGroupToolPolicy({ cfg, groupId: "1203630@g.us" })).toEqual({
+      deny: ["exec"],
+    });
+    expect(resolveWhatsAppGroupToolPolicy({ cfg, groupId: "other@g.us" })).toEqual({
+      allow: ["message.send"],
+    });
+  });
+});

package/src/group-policy.ts

@@ -0,0 +1,40 @@
+import {
+  resolveChannelGroupRequireMention,
+  resolveChannelGroupToolsPolicy,
+  type GroupToolPolicyConfig,
+} from "openclaw/plugin-sdk/channel-policy";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+type WhatsAppGroupContext = {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  groupId?: string | null;
+  senderId?: string | null;
+  senderName?: string | null;
+  senderUsername?: string | null;
+  senderE164?: string | null;
+};
+
+export function resolveWhatsAppGroupRequireMention(params: WhatsAppGroupContext): boolean {
+  return resolveChannelGroupRequireMention({
+    cfg: params.cfg,
+    channel: "whatsapp",
+    groupId: params.groupId,
+    accountId: params.accountId,
+  });
+}
+
+export function resolveWhatsAppGroupToolPolicy(
+  params: WhatsAppGroupContext,
+): GroupToolPolicyConfig | undefined {
+  return resolveChannelGroupToolsPolicy({
+    cfg: params.cfg,
+    channel: "whatsapp",
+    groupId: params.groupId,
+    accountId: params.accountId,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  });
+}

package/src/group-session-contract.ts

@@ -0,0 +1,20 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export function resolveLegacyGroupSessionKey(ctx: { From?: string }): {
+  key: string;
+  channel: string;
+  id: string;
+  chatType: "group";
+} | null {
+  const from = typeof ctx.From === "string" ? ctx.From.trim() : "";
+  const normalized = normalizeLowercaseStringOrEmpty(from);
+  if (!from || from.includes(":") || !normalized.endsWith("@g.us")) {
+    return null;
+  }
+  return {
+    key: `whatsapp:group:${normalized}`,
+    channel: "whatsapp",
+    id: normalized,
+    chatType: "group",
+  };
+}

package/src/group-session-key.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { resolveWhatsAppGroupSessionRoute, __testing } from "./group-session-key.js";
+
+describe("resolveWhatsAppGroupSessionRoute", () => {
+  it("keeps default-account group routes unchanged", () => {
+    const route = {
+      agentId: "main",
+      channel: "whatsapp",
+      accountId: "default",
+      sessionKey: "agent:main:whatsapp:group:123@g.us",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    } as const;
+
+    expect(resolveWhatsAppGroupSessionRoute(route)).toEqual(route);
+  });
+
+  it("scopes named-account group routes through an account-specific thread suffix", () => {
+    const route = {
+      agentId: "main",
+      channel: "whatsapp",
+      accountId: "work",
+      sessionKey: "agent:main:whatsapp:group:123@g.us",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    } as const;
+
+    expect(resolveWhatsAppGroupSessionRoute(route)).toEqual({
+      ...route,
+      sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
+    });
+  });
+
+  it("derives the legacy group session key from a named-account scoped group route", () => {
+    expect(
+      __testing.resolveWhatsAppLegacyGroupSessionKey({
+        accountId: "work",
+        sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
+      }),
+    ).toBe("agent:main:whatsapp:group:123@g.us");
+  });
+
+  it("normalizes mixed-case account ids when resolving legacy scoped group keys", () => {
+    expect(
+      __testing.resolveWhatsAppLegacyGroupSessionKey({
+        accountId: "Work",
+        sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
+      }),
+    ).toBe("agent:main:whatsapp:group:123@g.us");
+  });
+});

package/src/group-session-key.ts

@@ -0,0 +1,41 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  resolveThreadSessionKeys,
+  type ResolvedAgentRoute,
+} from "openclaw/plugin-sdk/routing";
+
+function resolveWhatsAppGroupAccountThreadId(accountId: string): string {
+  return `whatsapp-account-${normalizeAccountId(accountId)}`;
+}
+
+export function resolveWhatsAppLegacyGroupSessionKey(params: {
+  sessionKey: string;
+  accountId?: string | null;
+}): string | null {
+  const accountId = normalizeAccountId(params.accountId);
+  if (!accountId || accountId === DEFAULT_ACCOUNT_ID || !params.sessionKey.includes(":group:")) {
+    return null;
+  }
+  const suffix = `:thread:${resolveWhatsAppGroupAccountThreadId(accountId)}`;
+  return params.sessionKey.endsWith(suffix) ? params.sessionKey.slice(0, -suffix.length) : null;
+}
+
+export function resolveWhatsAppGroupSessionRoute(route: ResolvedAgentRoute): ResolvedAgentRoute {
+  if (route.accountId === DEFAULT_ACCOUNT_ID || !route.sessionKey.includes(":group:")) {
+    return route;
+  }
+  const scopedSession = resolveThreadSessionKeys({
+    baseSessionKey: route.sessionKey,
+    threadId: resolveWhatsAppGroupAccountThreadId(route.accountId),
+  });
+  return {
+    ...route,
+    sessionKey: scopedSession.sessionKey,
+  };
+}
+
+export const __testing = {
+  resolveWhatsAppGroupAccountThreadId,
+  resolveWhatsAppLegacyGroupSessionKey,
+};

package/src/heartbeat-recipients.runtime.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+export { normalizeE164 } from "openclaw/plugin-sdk/account-resolution";
+export { readChannelAllowFromStoreSync } from "openclaw/plugin-sdk/channel-pairing";
+export { normalizeChannelId } from "openclaw/plugin-sdk/channel-targets";
+export { loadSessionStore, resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime";
+export type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";