@openclaw/whatsapp 2026.5.1-beta.1

package/src/shared.ts

@@ -0,0 +1,291 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-core";
+import { describeAccountSnapshot } from "openclaw/plugin-sdk/account-helpers";
+import { normalizeE164 } from "openclaw/plugin-sdk/account-resolution";
+import {
+  adaptScopedAccountAccessor,
+  createScopedChannelConfigAdapter,
+  createScopedDmSecurityResolver,
+} from "openclaw/plugin-sdk/channel-config-helpers";
+import {
+  collectOpenGroupPolicyRouteAllowlistWarnings,
+  createAllowlistProviderGroupPolicyWarningCollector,
+} from "openclaw/plugin-sdk/channel-policy";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import { createChannelPluginBase, getChatChannelMeta } from "openclaw/plugin-sdk/core";
+import {
+  createDelegatedSetupWizardProxy,
+  type ChannelSetupWizard,
+} from "openclaw/plugin-sdk/setup-runtime";
+import {
+  hasAnyWhatsAppAuth,
+  listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+  resolveWhatsAppAccount,
+  type ResolvedWhatsAppAccount,
+} from "./accounts.js";
+import { formatWhatsAppConfigAllowFromEntries } from "./config-accessors.js";
+import { WhatsAppChannelConfigSchema } from "./config-schema.js";
+import { whatsappDoctor } from "./doctor.js";
+import { resolveLegacyGroupSessionKey } from "./group-session-contract.js";
+import {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./security-contract.js";
+import { applyWhatsAppSecurityConfigFixes } from "./security-fix.js";
+import {
+  canonicalizeLegacySessionKey,
+  deriveLegacySessionChatType,
+  isLegacyGroupSessionKey,
+} from "./session-contract.js";
+
+const WHATSAPP_CHANNEL = "whatsapp" as const;
+
+const WHATSAPP_GROUP_SCOPE_FIELDS = ["groupPolicy", "groupAllowFrom", "groups"] as const;
+
+type WhatsAppGroupScopeField = (typeof WHATSAPP_GROUP_SCOPE_FIELDS)[number];
+
+function resolveWhatsAppAccountKey(
+  accounts: Record<string, unknown> | undefined,
+  accountId: string,
+): string | undefined {
+  if (!accounts) {
+    return undefined;
+  }
+  if (Object.hasOwn(accounts, accountId)) {
+    return accountId;
+  }
+  const normalizedAccountId = accountId.trim().toLowerCase();
+  return Object.keys(accounts).find((key) => key.trim().toLowerCase() === normalizedAccountId);
+}
+
+function resolveWhatsAppGroupScopeBasePath(params: {
+  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+  accountId?: string | null;
+}): string {
+  const accountId =
+    typeof params.accountId === "string"
+      ? params.accountId.trim() || DEFAULT_ACCOUNT_ID
+      : DEFAULT_ACCOUNT_ID;
+  const accounts = params.cfg.channels?.whatsapp?.accounts;
+  const accountKey = resolveWhatsAppAccountKey(accounts, accountId);
+  const defaultAccountKey = resolveWhatsAppAccountKey(accounts, DEFAULT_ACCOUNT_ID);
+  const accountConfig = accountKey ? accounts?.[accountKey] : undefined;
+  const defaultAccountConfig = defaultAccountKey ? accounts?.[defaultAccountKey] : undefined;
+  const matchesAnyGroupScopeField = (config: Record<string, unknown> | undefined): boolean =>
+    WHATSAPP_GROUP_SCOPE_FIELDS.some((field) => config?.[field] !== undefined);
+  if (matchesAnyGroupScopeField(accountConfig)) {
+    return `channels.whatsapp.accounts.${accountKey}`;
+  }
+  if (accountId !== DEFAULT_ACCOUNT_ID && matchesAnyGroupScopeField(defaultAccountConfig)) {
+    return `channels.whatsapp.accounts.${defaultAccountKey}`;
+  }
+  return "channels.whatsapp";
+}
+
+function resolveWhatsAppConfigPath(params: {
+  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+  accountId?: string | null;
+  field: WhatsAppGroupScopeField;
+}): string {
+  return `${resolveWhatsAppGroupScopeBasePath(params)}.${params.field}`;
+}
+
+export async function loadWhatsAppChannelRuntime() {
+  return await import("./channel.runtime.js");
+}
+
+async function loadWhatsAppSetupSurface() {
+  return await import("./setup-surface.js");
+}
+
+export const whatsappSetupWizardProxy = createWhatsAppSetupWizardProxy(
+  async () => (await loadWhatsAppSetupSurface()).whatsappSetupWizard,
+);
+
+const whatsappConfigAdapter = createScopedChannelConfigAdapter<ResolvedWhatsAppAccount>({
+  sectionKey: WHATSAPP_CHANNEL,
+  listAccountIds: listWhatsAppAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveWhatsAppAccount),
+  defaultAccountId: resolveDefaultWhatsAppAccountId,
+  clearBaseFields: [],
+  allowTopLevel: false,
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: (allowFrom) => formatWhatsAppConfigAllowFromEntries(allowFrom),
+  resolveDefaultTo: (account) => account.defaultTo,
+});
+
+const whatsappResolveDmPolicy = createScopedDmSecurityResolver<ResolvedWhatsAppAccount>({
+  channelKey: WHATSAPP_CHANNEL,
+  resolvePolicy: (account) => account.dmPolicy,
+  resolveAllowFrom: (account) => account.allowFrom,
+  policyPathSuffix: "dmPolicy",
+  normalizeEntry: (raw) => normalizeE164(raw),
+  inheritSharedDefaultsFromDefaultAccount: true,
+});
+
+function createWhatsAppSetupWizardProxy(
+  loadWizard: () => Promise<ChannelSetupWizard>,
+): ChannelSetupWizard {
+  return createDelegatedSetupWizardProxy({
+    channel: WHATSAPP_CHANNEL,
+    loadWizard,
+    status: {
+      configuredLabel: "linked",
+      unconfiguredLabel: "not linked",
+      configuredHint: "linked",
+      unconfiguredHint: "not linked",
+      configuredScore: 5,
+      unconfiguredScore: 4,
+    },
+    resolveShouldPromptAccountIds: (params) => params.shouldPromptAccountIds,
+    credentials: [],
+    delegateFinalize: true,
+    disable: (cfg) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        whatsapp: {
+          ...cfg.channels?.whatsapp,
+          enabled: false,
+        },
+      },
+    }),
+    onAccountRecorded: (accountId, options) => {
+      options?.onAccountId?.(WHATSAPP_CHANNEL, accountId);
+    },
+  });
+}
+
+export function createWhatsAppPluginBase(params: {
+  groups: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["groups"]>;
+  setupWizard: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setupWizard"]>;
+  setup: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setup"]>;
+  isConfigured: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["config"]>["isConfigured"];
+}) {
+  const collectWhatsAppSecurityWarnings = createAllowlistProviderGroupPolicyWarningCollector<{
+    account: ResolvedWhatsAppAccount;
+    cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+    accountId?: string | null;
+  }>({
+    providerConfigPresent: (cfg) => cfg.channels?.whatsapp !== undefined,
+    resolveGroupPolicy: ({ account }) => account.groupPolicy,
+    collect: ({ account, accountId, cfg, groupPolicy }) =>
+      collectOpenGroupPolicyRouteAllowlistWarnings({
+        groupPolicy,
+        routeAllowlistConfigured:
+          Boolean(account.groups) && Object.keys(account.groups ?? {}).length > 0,
+        restrictSenders: {
+          surface: "WhatsApp groups",
+          openScope: "any member in allowed groups",
+          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
+          groupAllowFromPath: resolveWhatsAppConfigPath({
+            cfg,
+            accountId,
+            field: "groupAllowFrom",
+          }),
+        },
+        noRouteAllowlist: {
+          surface: "WhatsApp groups",
+          routeAllowlistPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groups" }),
+          routeScope: "group",
+          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
+          groupAllowFromPath: resolveWhatsAppConfigPath({
+            cfg,
+            accountId,
+            field: "groupAllowFrom",
+          }),
+        },
+      }),
+  });
+  const base = createChannelPluginBase({
+    id: WHATSAPP_CHANNEL,
+    meta: {
+      ...getChatChannelMeta(WHATSAPP_CHANNEL),
+      showConfigured: false,
+      quickstartAllowFrom: true,
+      forceAccountBinding: true,
+      preferSessionLookupForAnnounceTarget: true,
+    },
+    setupWizard: params.setupWizard,
+    capabilities: {
+      chatTypes: ["direct", "group"],
+      polls: true,
+      reactions: true,
+      media: true,
+      tts: {
+        voice: {
+          synthesisTarget: "voice-note",
+          transcodesAudio: true,
+        },
+      },
+    },
+    reload: { configPrefixes: ["web"], noopPrefixes: ["channels.whatsapp"] },
+    gatewayMethods: ["web.login.start", "web.login.wait"],
+    configSchema: WhatsAppChannelConfigSchema,
+    config: {
+      ...whatsappConfigAdapter,
+      isEnabled: (account, cfg) => account.enabled && cfg.web?.enabled !== false,
+      disabledReason: () => "disabled",
+      isConfigured: params.isConfigured,
+      hasPersistedAuthState: ({ cfg }) => hasAnyWhatsAppAuth(cfg),
+      unconfiguredReason: () => "not linked",
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured: Boolean(account.authDir),
+          extra: {
+            linked: Boolean(account.authDir),
+            dmPolicy: account.dmPolicy,
+            allowFrom: account.allowFrom,
+          },
+        }),
+    },
+    security: {
+      applyConfigFixes: applyWhatsAppSecurityConfigFixes,
+      resolveDmPolicy: whatsappResolveDmPolicy,
+      collectWarnings: collectWhatsAppSecurityWarnings,
+    },
+    doctor: whatsappDoctor,
+    setup: params.setup,
+    groups: params.groups,
+  });
+  return {
+    ...base,
+    setupWizard: base.setupWizard!,
+    capabilities: base.capabilities!,
+    reload: base.reload!,
+    gatewayMethods: base.gatewayMethods!,
+    configSchema: base.configSchema!,
+    config: base.config!,
+    messaging: {
+      defaultMarkdownTableMode: "bullets",
+      deriveLegacySessionChatType,
+      resolveLegacyGroupSessionKey,
+      isLegacyGroupSessionKey,
+      canonicalizeLegacySessionKey: (params) =>
+        canonicalizeLegacySessionKey({ key: params.key, agentId: params.agentId }),
+    },
+    secrets: {
+      unsupportedSecretRefSurfacePatterns,
+      collectUnsupportedSecretRefConfigCandidates,
+    },
+    security: base.security!,
+    groups: base.groups!,
+  } satisfies Pick<
+    ChannelPlugin<ResolvedWhatsAppAccount>,
+    | "id"
+    | "meta"
+    | "setupWizard"
+    | "capabilities"
+    | "reload"
+    | "gatewayMethods"
+    | "configSchema"
+    | "config"
+    | "messaging"
+    | "secrets"
+    | "security"
+    | "doctor"
+    | "setup"
+    | "groups"
+  >;
+}

package/src/socket-timing.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_WHATSAPP_SOCKET_TIMING, resolveWhatsAppSocketTiming } from "./socket-timing.js";
+
+describe("resolveWhatsAppSocketTiming", () => {
+  it("uses OpenClaw's explicit WhatsApp Web socket defaults", () => {
+    expect(resolveWhatsAppSocketTiming({})).toEqual(DEFAULT_WHATSAPP_SOCKET_TIMING);
+  });
+
+  it("reads Baileys timing values from web.whatsapp config", () => {
+    expect(
+      resolveWhatsAppSocketTiming({
+        web: {
+          whatsapp: {
+            keepAliveIntervalMs: 10_000,
+            connectTimeoutMs: 90_000,
+            defaultQueryTimeoutMs: 120_000,
+          },
+        },
+      }),
+    ).toEqual({
+      keepAliveIntervalMs: 10_000,
+      connectTimeoutMs: 90_000,
+      defaultQueryTimeoutMs: 120_000,
+    });
+  });
+
+  it("lets call-site overrides take precedence over config", () => {
+    expect(
+      resolveWhatsAppSocketTiming(
+        {
+          web: {
+            whatsapp: {
+              keepAliveIntervalMs: 10_000,
+              connectTimeoutMs: 90_000,
+              defaultQueryTimeoutMs: 120_000,
+            },
+          },
+        },
+        {
+          keepAliveIntervalMs: 20_000,
+        },
+      ),
+    ).toEqual({
+      keepAliveIntervalMs: 20_000,
+      connectTimeoutMs: 90_000,
+      defaultQueryTimeoutMs: 120_000,
+    });
+  });
+});

package/src/socket-timing.ts

@@ -0,0 +1,38 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export type WhatsAppSocketTimingOptions = {
+  keepAliveIntervalMs?: number;
+  connectTimeoutMs?: number;
+  defaultQueryTimeoutMs?: number;
+};
+
+export const DEFAULT_WHATSAPP_SOCKET_TIMING: Required<WhatsAppSocketTimingOptions> = {
+  keepAliveIntervalMs: 25_000,
+  connectTimeoutMs: 60_000,
+  defaultQueryTimeoutMs: 60_000,
+};
+
+function positiveInteger(value: number | undefined): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveWhatsAppSocketTiming(
+  cfg: OpenClawConfig,
+  overrides?: WhatsAppSocketTimingOptions,
+): Required<WhatsAppSocketTimingOptions> {
+  const configured = cfg.web?.whatsapp;
+  return {
+    keepAliveIntervalMs:
+      positiveInteger(overrides?.keepAliveIntervalMs) ??
+      positiveInteger(configured?.keepAliveIntervalMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.keepAliveIntervalMs,
+    connectTimeoutMs:
+      positiveInteger(overrides?.connectTimeoutMs) ??
+      positiveInteger(configured?.connectTimeoutMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.connectTimeoutMs,
+    defaultQueryTimeoutMs:
+      positiveInteger(overrides?.defaultQueryTimeoutMs) ??
+      positiveInteger(configured?.defaultQueryTimeoutMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,
+  };
+}

package/src/state-migrations.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import type { ChannelLegacyStateMigrationPlan } from "openclaw/plugin-sdk/channel-contract";
+
+function fileExists(pathValue: string): boolean {
+  try {
+    return fs.existsSync(pathValue) && fs.statSync(pathValue).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isLegacyWhatsAppAuthFile(name: string): boolean {
+  if (name === "creds.json" || name === "creds.json.bak") {
+    return true;
+  }
+  if (!name.endsWith(".json")) {
+    return false;
+  }
+  return /^(app-state-sync|session|sender-key|pre-key)-/.test(name);
+}
+
+export function detectWhatsAppLegacyStateMigrations(params: {
+  oauthDir: string;
+}): ChannelLegacyStateMigrationPlan[] {
+  const targetDir = path.join(params.oauthDir, "whatsapp", DEFAULT_ACCOUNT_ID);
+  const entries = (() => {
+    try {
+      return fs.readdirSync(params.oauthDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+  })();
+
+  return entries.flatMap((entry) => {
+    if (!entry.isFile() || entry.name === "oauth.json" || !isLegacyWhatsAppAuthFile(entry.name)) {
+      return [];
+    }
+    const sourcePath = path.join(params.oauthDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (fileExists(targetPath)) {
+      return [];
+    }
+    return [
+      {
+        kind: "move" as const,
+        label: `WhatsApp auth ${entry.name}`,
+        sourcePath,
+        targetPath,
+      },
+    ];
+  });
+}

package/src/status-issues.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import { collectWhatsAppStatusIssues } from "./status-issues.js";
+
+describe("collectWhatsAppStatusIssues", () => {
+  it("reports unlinked enabled accounts", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        linked: false,
+      },
+    ]);
+
+    expect(issues).toEqual([
+      expect.objectContaining({
+        channel: "whatsapp",
+        accountId: "default",
+        kind: "auth",
+      }),
+    ]);
+  });
+
+  it("reports auth reads that are still stabilizing", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        statusState: "unstable",
+      },
+    ]);
+
+    expect(issues).toEqual([
+      expect.objectContaining({
+        channel: "whatsapp",
+        accountId: "default",
+        kind: "auth",
+        message: "Auth state is still stabilizing.",
+      }),
+    ]);
+  });
+
+  it("reports linked but disconnected runtime state", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "work",
+        enabled: true,
+        linked: true,
+        running: true,
+        connected: false,
+        reconnectAttempts: 2,
+        lastError: "socket closed",
+      },
+    ]);
+
+    expect(issues).toEqual([
+      expect.objectContaining({
+        channel: "whatsapp",
+        accountId: "work",
+        kind: "runtime",
+        message: "Linked but disconnected (reconnectAttempts=2): socket closed",
+      }),
+    ]);
+  });
+
+  it("reports linked but stale runtime state even while connected", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        linked: true,
+        running: true,
+        connected: true,
+        healthState: "stale",
+        lastInboundAt: Date.now() - 2 * 60_000,
+      },
+    ]);
+
+    expect(issues).toEqual([
+      expect.objectContaining({
+        channel: "whatsapp",
+        accountId: "default",
+        kind: "runtime",
+        message: expect.stringContaining("Linked but stale"),
+      }),
+    ]);
+  });
+
+  it("reports recently reconnected accounts even when the socket is currently healthy", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        linked: true,
+        running: true,
+        connected: true,
+        reconnectAttempts: 3,
+        healthState: "healthy",
+        lastDisconnect: {
+          at: Date.now() - 2 * 60_000,
+          status: 408,
+          error: "status=408 Request Time-out Connection was lost",
+        },
+      },
+    ]);
+
+    expect(issues).toEqual([
+      expect.objectContaining({
+        channel: "whatsapp",
+        accountId: "default",
+        kind: "runtime",
+        message:
+          "Linked but recently reconnected (reconnectAttempts=3): status=408 Request Time-out Connection was lost",
+      }),
+    ]);
+  });
+
+  it("does not report old reconnect history after a stable healthy period", () => {
+    const issues = collectWhatsAppStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        linked: true,
+        running: true,
+        connected: true,
+        reconnectAttempts: 1,
+        healthState: "healthy",
+        lastDisconnect: {
+          at: Date.now() - 60 * 60_000,
+          status: 408,
+          error: "old disconnect",
+        },
+      },
+    ]);
+
+    expect(issues).toEqual([]);
+  });
+});