@openclaw/whatsapp 2026.5.1-beta.1

package/src/channel.ts

@@ -0,0 +1,336 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import { buildDmGroupAccountAllowlistAdapter } from "openclaw/plugin-sdk/allowlist-config-edit";
+import { createChatChannelPlugin, type ChannelPlugin } from "openclaw/plugin-sdk/channel-core";
+import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import {
+  createAsyncComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "openclaw/plugin-sdk/status-helpers";
+import { resolveWhatsAppAccount, type ResolvedWhatsAppAccount } from "./accounts.js";
+import { createWhatsAppLoginTool } from "./agent-tools-login.js";
+import { whatsappApprovalAuth } from "./approval-auth.js";
+import type { WebChannelStatus } from "./auto-reply/types.js";
+import {
+  describeWhatsAppMessageActions,
+  resolveWhatsAppAgentReactionGuidance,
+} from "./channel-actions.js";
+import { whatsappChannelOutbound } from "./channel-outbound.js";
+import { whatsappCommandPolicy } from "./command-policy.js";
+import { formatWhatsAppConfigAllowFromEntries } from "./config-accessors.js";
+import {
+  resolveWhatsAppGroupIntroHint,
+  resolveWhatsAppMentionStripRegexes,
+} from "./group-intro.js";
+import {
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppGroupToolPolicy,
+} from "./group-policy.js";
+import { resolveWhatsAppHeartbeatRecipients } from "./heartbeat-recipients.js";
+import { checkWhatsAppHeartbeatReady } from "./heartbeat.js";
+import {
+  isWhatsAppGroupJid,
+  looksLikeWhatsAppTargetId,
+  normalizeWhatsAppMessagingTarget,
+  normalizeWhatsAppTarget,
+} from "./normalize.js";
+import { getWhatsAppRuntime } from "./runtime.js";
+import { sendTypingWhatsApp } from "./send.js";
+import { resolveWhatsAppOutboundSessionRoute } from "./session-route.js";
+import { whatsappSetupAdapter } from "./setup-core.js";
+import {
+  createWhatsAppPluginBase,
+  loadWhatsAppChannelRuntime,
+  whatsappSetupWizardProxy,
+} from "./shared.js";
+import { detectWhatsAppLegacyStateMigrations } from "./state-migrations.js";
+import { collectWhatsAppStatusIssues } from "./status-issues.js";
+
+const loadWhatsAppDirectoryConfig = createLazyRuntimeModule(() => import("./directory-config.js"));
+const loadWhatsAppChannelReactAction = createLazyRuntimeModule(
+  () => import("./channel-react-action.js"),
+);
+
+function parseWhatsAppExplicitTarget(raw: string) {
+  const normalized = normalizeWhatsAppTarget(raw);
+  if (!normalized) {
+    return null;
+  }
+  return {
+    to: normalized,
+    chatType: isWhatsAppGroupJid(normalized) ? ("group" as const) : ("direct" as const),
+  };
+}
+
+export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
+  createChatChannelPlugin<ResolvedWhatsAppAccount>({
+    pairing: {
+      idLabel: "whatsappSenderId",
+    },
+    outbound: whatsappChannelOutbound,
+    threading: {
+      scopedAccountReplyToMode: {
+        resolveAccount: (cfg, accountId) => resolveWhatsAppAccount({ cfg, accountId }),
+        resolveReplyToMode: (account) => account.replyToMode,
+      },
+    },
+    base: {
+      ...createWhatsAppPluginBase({
+        groups: {
+          resolveRequireMention: resolveWhatsAppGroupRequireMention,
+          resolveToolPolicy: resolveWhatsAppGroupToolPolicy,
+          resolveGroupIntroHint: resolveWhatsAppGroupIntroHint,
+        },
+        setupWizard: whatsappSetupWizardProxy,
+        setup: whatsappSetupAdapter,
+        isConfigured: async (account) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          return (await channelRuntime.readWebAuthState(account.authDir)) === "linked";
+        },
+      }),
+      agentTools: () => [createWhatsAppLoginTool()],
+      allowlist: buildDmGroupAccountAllowlistAdapter({
+        channelId: "whatsapp",
+        resolveAccount: resolveWhatsAppAccount,
+        normalize: ({ values }) => formatWhatsAppConfigAllowFromEntries(values),
+        resolveDmAllowFrom: (account) => account.allowFrom,
+        resolveGroupAllowFrom: (account) => account.groupAllowFrom,
+        resolveDmPolicy: (account) => account.dmPolicy,
+        resolveGroupPolicy: (account) => account.groupPolicy,
+      }),
+      mentions: {
+        stripRegexes: ({ ctx }) => resolveWhatsAppMentionStripRegexes(ctx),
+      },
+      commands: whatsappCommandPolicy,
+      agentPrompt: {
+        reactionGuidance: ({ cfg, accountId }) => {
+          const level = resolveWhatsAppAgentReactionGuidance({
+            cfg,
+            accountId: accountId ?? undefined,
+          });
+          return level ? { level, channelLabel: "WhatsApp" } : undefined;
+        },
+      },
+      messaging: {
+        targetPrefixes: ["whatsapp"],
+        normalizeTarget: normalizeWhatsAppMessagingTarget,
+        resolveOutboundSessionRoute: (params) => resolveWhatsAppOutboundSessionRoute(params),
+        parseExplicitTarget: ({ raw }) => parseWhatsAppExplicitTarget(raw),
+        inferTargetChatType: ({ to }) => parseWhatsAppExplicitTarget(to)?.chatType,
+        targetResolver: {
+          looksLikeId: looksLikeWhatsAppTargetId,
+          hint: "<E.164|group JID>",
+        },
+      },
+      directory: {
+        self: async ({ cfg, accountId }) => {
+          const account = resolveWhatsAppAccount({ cfg, accountId });
+          const { e164, jid } = (await loadWhatsAppChannelRuntime()).readWebSelfId(account.authDir);
+          const id = e164 ?? jid;
+          if (!id) {
+            return null;
+          }
+          return {
+            kind: "user",
+            id,
+            name: account.name,
+            raw: { e164, jid },
+          };
+        },
+        listPeers: async (params) =>
+          (await loadWhatsAppDirectoryConfig()).listWhatsAppDirectoryPeersFromConfig(params),
+        listGroups: async (params) =>
+          (await loadWhatsAppDirectoryConfig()).listWhatsAppDirectoryGroupsFromConfig(params),
+      },
+      actions: {
+        describeMessageTool: ({ cfg, accountId }) =>
+          describeWhatsAppMessageActions({ cfg, accountId }),
+        supportsAction: ({ action }) => action === "react",
+        resolveExecutionMode: ({ action }) => (action === "react" ? "gateway" : "local"),
+        handleAction: async ({ action, params, cfg, accountId, requesterSenderId, toolContext }) =>
+          await (
+            await loadWhatsAppChannelReactAction()
+          ).handleWhatsAppReactAction({
+            action,
+            params,
+            cfg,
+            accountId,
+            requesterSenderId,
+            toolContext,
+          }),
+      },
+      approvalCapability: whatsappApprovalAuth,
+      auth: {
+        login: async ({ cfg, accountId, runtime, verbose }) => {
+          const resolvedAccountId =
+            accountId?.trim() ||
+            whatsappPlugin.config.defaultAccountId?.(cfg) ||
+            DEFAULT_ACCOUNT_ID;
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).loginWeb(Boolean(verbose), undefined, runtime, resolvedAccountId);
+        },
+      },
+      lifecycle: {
+        detectLegacyStateMigrations: ({ oauthDir }) =>
+          detectWhatsAppLegacyStateMigrations({ oauthDir }),
+      },
+      heartbeat: {
+        checkReady: async ({ cfg, accountId, deps }) =>
+          await checkWhatsAppHeartbeatReady({ cfg, accountId: accountId ?? undefined, deps }),
+        sendTyping: async ({ cfg, to, accountId }) => {
+          await sendTypingWhatsApp(to, {
+            cfg,
+            ...(accountId ? { accountId } : {}),
+          });
+        },
+        resolveRecipients: ({ cfg, opts }) => resolveWhatsAppHeartbeatRecipients(cfg, opts),
+      },
+      status: createAsyncComputedAccountStatusAdapter<ResolvedWhatsAppAccount>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, {
+          connected: false,
+          reconnectAttempts: 0,
+          lastConnectedAt: null,
+          lastDisconnect: null,
+          lastInboundAt: null,
+          lastMessageAt: null,
+          lastEventAt: null,
+          healthState: "stopped",
+        }),
+        collectStatusIssues: collectWhatsAppStatusIssues,
+        buildChannelSummary: async ({ account, snapshot }) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          const authDir = account.authDir;
+          const auth = authDir
+            ? await channelRuntime.readWebAuthSnapshot(authDir)
+            : {
+                state: "not-linked" as const,
+                authAgeMs: null,
+                selfId: { e164: null, jid: null, lid: null },
+              };
+          const linked =
+            typeof snapshot.linked === "boolean"
+              ? snapshot.linked
+              : auth.state === "unstable"
+                ? undefined
+                : auth.state === "linked";
+          const summaryAuthState =
+            auth.state === "unstable"
+              ? auth.state
+              : linked === true
+                ? "linked"
+                : linked === false
+                  ? "not-linked"
+                  : undefined;
+          const statusState = summaryAuthState === undefined ? undefined : summaryAuthState;
+          const configured =
+            auth.state === "unstable"
+              ? typeof snapshot.configured === "boolean"
+                ? snapshot.configured
+                : true
+              : typeof linked === "boolean"
+                ? linked
+                : auth.state === "linked";
+          const authAgeMs = typeof linked === "boolean" && linked ? auth.authAgeMs : null;
+          const self =
+            typeof linked === "boolean" && linked
+              ? auth.selfId
+              : { e164: null, jid: null, lid: null };
+          return {
+            configured,
+            ...(statusState ? { statusState } : {}),
+            ...(typeof linked === "boolean" ? { linked } : {}),
+            authAgeMs,
+            self,
+            running: snapshot.running ?? false,
+            connected: snapshot.connected ?? false,
+            lastConnectedAt: snapshot.lastConnectedAt ?? null,
+            lastDisconnect: snapshot.lastDisconnect ?? null,
+            reconnectAttempts: snapshot.reconnectAttempts,
+            lastInboundAt: snapshot.lastInboundAt ?? snapshot.lastMessageAt ?? null,
+            lastMessageAt: snapshot.lastMessageAt ?? null,
+            lastEventAt: snapshot.lastEventAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            healthState: snapshot.healthState ?? undefined,
+          };
+        },
+        resolveAccountSnapshot: async ({ account, runtime }) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          const authState = await channelRuntime.readWebAuthState(account.authDir);
+          return {
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: true,
+            extra: {
+              statusState: authState,
+              ...(authState === "linked"
+                ? { linked: true }
+                : authState === "not-linked"
+                  ? { linked: false }
+                  : {}),
+              connected: runtime?.connected ?? false,
+              reconnectAttempts: runtime?.reconnectAttempts,
+              lastConnectedAt: runtime?.lastConnectedAt ?? null,
+              lastDisconnect: runtime?.lastDisconnect ?? null,
+              lastInboundAt: runtime?.lastInboundAt ?? runtime?.lastMessageAt ?? null,
+              lastMessageAt: runtime?.lastMessageAt ?? null,
+              lastEventAt: runtime?.lastEventAt ?? null,
+              healthState: runtime?.healthState ?? undefined,
+              dmPolicy: account.dmPolicy,
+              allowFrom: account.allowFrom,
+            },
+          };
+        },
+        resolveAccountState: ({ configured }) => (configured ? "linked" : "not linked"),
+        logSelfId: ({ account, runtime, includeChannelPrefix }) => {
+          void loadWhatsAppChannelRuntime().then((runtimeExports) =>
+            runtimeExports.logWebSelfId(account.authDir, runtime, includeChannelPrefix),
+          );
+        },
+      }),
+      gateway: {
+        startAccount: async (ctx) => {
+          const account = ctx.account;
+          const { e164, jid } = (await loadWhatsAppChannelRuntime()).readWebSelfId(account.authDir);
+          const identity = e164 ? e164 : jid ? `jid ${jid}` : "unknown";
+          ctx.log?.info(`[${account.accountId}] starting provider (${identity})`);
+          return (await loadWhatsAppChannelRuntime()).monitorWebChannel(
+            getWhatsAppRuntime().logging.shouldLogVerbose(),
+            undefined,
+            true,
+            undefined,
+            ctx.runtime,
+            ctx.abortSignal,
+            {
+              statusSink: (next: WebChannelStatus) =>
+                ctx.setStatus({ accountId: ctx.accountId, ...next }),
+              accountId: account.accountId,
+            },
+          );
+        },
+        loginWithQrStart: async ({ accountId, force, timeoutMs, verbose }) =>
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).startWebLoginWithQr({
+            accountId,
+            force,
+            timeoutMs,
+            verbose,
+          }),
+        loginWithQrWait: async ({ accountId, timeoutMs, currentQrDataUrl }) =>
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).waitForWebLogin({ accountId, timeoutMs, currentQrDataUrl }),
+        logoutAccount: async ({ account, runtime }) => {
+          const cleared = await (
+            await loadWhatsAppChannelRuntime()
+          ).logoutWeb({
+            authDir: account.authDir,
+            isLegacyAuthDir: account.isLegacyAuthDir,
+            runtime,
+          });
+          return { cleared, loggedOut: cleared };
+        },
+      },
+    },
+  });

package/src/command-policy.ts

@@ -0,0 +1,7 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+export const whatsappCommandPolicy: NonNullable<ChannelPlugin["commands"]> = {
+  enforceOwnerForCommands: true,
+  preferSenderE164ForCommands: true,
+  skipWhenConfigEmpty: true,
+};

package/src/config-accessors.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatWhatsAppConfigAllowFromEntries,
+  resolveWhatsAppConfigAllowFrom,
+  resolveWhatsAppConfigDefaultTo,
+} from "./config-accessors.js";
+
+describe("whatsapp config accessors", () => {
+  it("reads merged allowFrom/defaultTo from resolved account config", () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          defaultTo: " root:chat ",
+          allowFrom: ["+49111"],
+          accounts: {
+            alt: {
+              defaultTo: " alt:chat ",
+              allowFrom: ["+49222", "+49333"],
+            },
+          },
+        },
+      },
+    };
+
+    expect(resolveWhatsAppConfigAllowFrom({ cfg, accountId: "alt" })).toEqual(["+49222", "+49333"]);
+    expect(resolveWhatsAppConfigDefaultTo({ cfg, accountId: "alt" })).toBe("alt:chat");
+  });
+
+  it("normalizes allowFrom entries like the channel plugin", () => {
+    expect(
+      formatWhatsAppConfigAllowFromEntries([" whatsapp:+49123 ", "*", "49124@s.whatsapp.net"]),
+    ).toEqual(["+49123", "*", "+49124"]);
+  });
+});

package/src/config-accessors.ts

@@ -0,0 +1,22 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveWhatsAppAccount } from "./accounts.js";
+import { normalizeWhatsAppAllowFromEntries } from "./normalize-target.js";
+
+export function resolveWhatsAppConfigAllowFrom(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): string[] {
+  return [...(resolveWhatsAppAccount(params).allowFrom ?? [])];
+}
+
+export function formatWhatsAppConfigAllowFromEntries(allowFrom: Array<string | number>): string[] {
+  return normalizeWhatsAppAllowFromEntries(allowFrom);
+}
+
+export function resolveWhatsAppConfigDefaultTo(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): string | undefined {
+  const defaultTo = resolveWhatsAppAccount(params).defaultTo?.trim();
+  return defaultTo || undefined;
+}

package/src/config-schema.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { WhatsAppConfigSchema } from "../config-api.js";
+
+function expectWhatsAppConfigValid(config: unknown) {
+  const res = WhatsAppConfigSchema.safeParse(config);
+  expect(res.success).toBe(true);
+  return res;
+}
+
+describe("whatsapp config schema", () => {
+  it('rejects dmPolicy="open" without allowFrom "*"', () => {
+    const res = WhatsAppConfigSchema.safeParse({
+      dmPolicy: "open",
+      allowFrom: ["+15555550123"],
+    });
+
+    expect(res.success).toBe(false);
+    if (!res.success) {
+      expect(res.error.issues[0]?.path.join(".")).toBe("allowFrom");
+    }
+  });
+
+  it('accepts dmPolicy="open" with allowFrom "*"', () => {
+    const res = WhatsAppConfigSchema.safeParse({ dmPolicy: "open", allowFrom: ["*"] });
+
+    expect(res.success).toBe(true);
+    if (res.success) {
+      expect(res.data.dmPolicy).toBe("open");
+    }
+  });
+
+  it("defaults dm/group policy", () => {
+    const res = WhatsAppConfigSchema.safeParse({});
+
+    expect(res.success).toBe(true);
+    if (res.success) {
+      expect(res.data.dmPolicy).toBe("pairing");
+      expect(res.data.groupPolicy).toBe("allowlist");
+    }
+  });
+
+  it("accepts historyLimit overrides per account", () => {
+    const res = WhatsAppConfigSchema.safeParse({
+      historyLimit: 9,
+      accounts: { work: { historyLimit: 4 } },
+    });
+
+    expect(res.success).toBe(true);
+    if (res.success) {
+      expect(res.data.historyLimit).toBe(9);
+      expect(res.data.accounts?.work?.historyLimit).toBe(4);
+    }
+  });
+
+  it("accepts textChunkLimit", () => {
+    const res = expectWhatsAppConfigValid({
+      allowFrom: ["+15555550123"],
+      textChunkLimit: 4444,
+    });
+
+    if (res.success) {
+      expect(res.data.textChunkLimit).toBe(4444);
+    }
+  });
+
+  it("accepts enabled", () => {
+    expectWhatsAppConfigValid({
+      enabled: true,
+    });
+  });
+
+  it("keeps inherited account defaults unset at account scope", () => {
+    const res = expectWhatsAppConfigValid({
+      dmPolicy: "allowlist",
+      groupPolicy: "open",
+      debounceMs: 250,
+      allowFrom: ["+15550001111"],
+      accounts: {
+        work: {
+          allowFrom: ["+15550002222"],
+        },
+      },
+    });
+
+    if (!res.success) {
+      return;
+    }
+    expect(res.data.dmPolicy).toBe("allowlist");
+    expect(res.data.groupPolicy).toBe("open");
+    expect(res.data.debounceMs).toBe(250);
+    expect(res.data.accounts?.work?.dmPolicy).toBeUndefined();
+    expect(res.data.accounts?.work?.groupPolicy).toBeUndefined();
+    expect(res.data.accounts?.work?.debounceMs).toBeUndefined();
+  });
+
+  it("accepts allowlist accounts inheriting allowFrom from accounts.default", () => {
+    expectWhatsAppConfigValid({
+      accounts: {
+        default: {
+          allowFrom: ["+15550001111"],
+        },
+        work: {
+          dmPolicy: "allowlist",
+        },
+      },
+    });
+  });
+
+  it("accepts allowlist accounts inheriting allowFrom from mixed-case accounts.Default", () => {
+    expectWhatsAppConfigValid({
+      accounts: {
+        Default: {
+          allowFrom: ["+15550001111"],
+        },
+        work: {
+          dmPolicy: "allowlist",
+        },
+      },
+    });
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,6 @@
+import { buildChannelConfigSchema, WhatsAppConfigSchema } from "../config-api.js";
+import { whatsAppChannelConfigUiHints } from "./config-ui-hints.js";
+
+export const WhatsAppChannelConfigSchema = buildChannelConfigSchema(WhatsAppConfigSchema, {
+  uiHints: whatsAppChannelConfigUiHints,
+});

package/src/config-ui-hints.ts

@@ -0,0 +1,24 @@
+import type { ChannelConfigUiHint } from "openclaw/plugin-sdk/core";
+
+export const whatsAppChannelConfigUiHints = {
+  "": {
+    label: "WhatsApp",
+    help: "WhatsApp channel provider configuration for access policy and message batching behavior. Use this section to tune responsiveness and direct-message routing safety for WhatsApp chats.",
+  },
+  dmPolicy: {
+    label: "WhatsApp DM Policy",
+    help: 'Direct message access control ("pairing" recommended). "open" requires channels.whatsapp.allowFrom=["*"].',
+  },
+  selfChatMode: {
+    label: "WhatsApp Self-Phone Mode",
+    help: "Same-phone setup (bot uses your personal WhatsApp number).",
+  },
+  debounceMs: {
+    label: "WhatsApp Message Debounce (ms)",
+    help: "Debounce window (ms) for batching rapid consecutive messages from the same sender (0 to disable).",
+  },
+  configWrites: {
+    label: "WhatsApp Config Writes",
+    help: "Allow WhatsApp to write config in response to channel events/commands (default: true).",
+  },
+} satisfies Record<string, ChannelConfigUiHint>;

package/src/connection-controller-registry.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from "vitest";
+
+type RegistryModule = typeof import("./connection-controller-registry.js");
+
+const registryModuleUrl = new URL("./connection-controller-registry.ts", import.meta.url).href;
+
+async function importRegistryModule(cacheBust: string): Promise<RegistryModule> {
+  return (await import(`${registryModuleUrl}?t=${cacheBust}`)) as RegistryModule;
+}
+
+describe("WhatsApp connection controller registry", () => {
+  it("shares registered controllers across duplicate module instances", async () => {
+    const first = await importRegistryModule(`first-${Date.now()}`);
+    const second = await importRegistryModule(`second-${Date.now()}`);
+    const controller = {
+      getActiveListener: vi.fn(() => null),
+    };
+
+    first.registerWhatsAppConnectionController("work", controller);
+
+    try {
+      expect(second.getRegisteredWhatsAppConnectionController("work")).toBe(controller);
+    } finally {
+      first.unregisterWhatsAppConnectionController("work", controller);
+    }
+  });
+});

package/src/connection-controller-registry.ts

@@ -0,0 +1,49 @@
+import type { ActiveWebListener } from "./inbound/types.js";
+
+type WhatsAppConnectionControllerHandle = {
+  getActiveListener(): ActiveWebListener | null;
+};
+
+type ConnectionRegistryState = {
+  controllers: Map<string, WhatsAppConnectionControllerHandle>;
+};
+
+const CONNECTION_REGISTRY_KEY = Symbol.for("openclaw.whatsapp.connectionControllerRegistry");
+
+function getConnectionRegistryState(): ConnectionRegistryState {
+  const globalState = globalThis as typeof globalThis & {
+    [CONNECTION_REGISTRY_KEY]?: ConnectionRegistryState;
+  };
+  const existing = globalState[CONNECTION_REGISTRY_KEY];
+  if (existing) {
+    return existing;
+  }
+  const created: ConnectionRegistryState = {
+    controllers: new Map<string, WhatsAppConnectionControllerHandle>(),
+  };
+  globalState[CONNECTION_REGISTRY_KEY] = created;
+  return created;
+}
+
+export function getRegisteredWhatsAppConnectionController(
+  accountId: string,
+): WhatsAppConnectionControllerHandle | null {
+  return getConnectionRegistryState().controllers.get(accountId) ?? null;
+}
+
+export function registerWhatsAppConnectionController(
+  accountId: string,
+  controller: WhatsAppConnectionControllerHandle,
+): void {
+  getConnectionRegistryState().controllers.set(accountId, controller);
+}
+
+export function unregisterWhatsAppConnectionController(
+  accountId: string,
+  controller: WhatsAppConnectionControllerHandle,
+): void {
+  const controllers = getConnectionRegistryState().controllers;
+  if (controllers.get(accountId) === controller) {
+    controllers.delete(accountId);
+  }
+}