@openclaw/whatsapp 2026.5.2-beta.1 → 2026.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/whatsapp",
-  "version": "2026.5.2-beta.1",
+  "version": "2026.5.2",
   "description": "OpenClaw WhatsApp channel plugin",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "openclaw": "workspace:*"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.5.2-beta.1"
+    "openclaw": ">=2026.5.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -61,10 +61,10 @@
       "minHostVersion": ">=2026.4.25"
     },
     "compat": {
-      "pluginApi": ">=2026.5.2-beta.1"
+      "pluginApi": ">=2026.5.2"
     },
     "build": {
-      "openclawVersion": "2026.5.2-beta.1"
+      "openclawVersion": "2026.5.2"
     },
     "release": {
       "publishToClawHub": true,

package/src/channel.ts

@@ -28,6 +28,7 @@ import {
 import { checkWhatsAppHeartbeatReady } from "./heartbeat.js";
 import {
   isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
   looksLikeWhatsAppTargetId,
   normalizeWhatsAppMessagingTarget,
   normalizeWhatsAppTarget,
@@ -56,7 +57,11 @@ function parseWhatsAppExplicitTarget(raw: string) {
   }
   return {
     to: normalized,
-    chatType: isWhatsAppGroupJid(normalized) ? ("group" as const) : ("direct" as const),
+    chatType: isWhatsAppGroupJid(normalized)
+      ? ("group" as const)
+      : isWhatsAppNewsletterJid(normalized)
+        ? ("channel" as const)
+        : ("direct" as const),
   };
 }
 
@@ -117,7 +122,7 @@ export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
         inferTargetChatType: ({ to }) => parseWhatsAppExplicitTarget(to)?.chatType,
         targetResolver: {
           looksLikeId: looksLikeWhatsAppTargetId,
-          hint: "<E.164|group JID>",
+          hint: "<E.164|group JID|newsletter JID>",
         },
       },
       directory: {

package/src/inbound/send-api.test.ts

@@ -260,6 +260,18 @@ describe("createWebSendApi", () => {
     expect(sendPresenceUpdate).toHaveBeenCalledWith("composing", "1555@s.whatsapp.net");
   });
 
+  it("does not send composing presence to newsletter JIDs", async () => {
+    await api.sendComposingTo("120363401234567890@newsletter");
+    expect(sendPresenceUpdate).not.toHaveBeenCalled();
+  });
+
+  it("preserves newsletter JIDs for outbound sends", async () => {
+    await api.sendMessage("120363401234567890@newsletter", "hello");
+    expect(sendMessage).toHaveBeenCalledWith("120363401234567890@newsletter", {
+      text: "hello",
+    });
+  });
+
   it("sends media as document when mediaType is undefined", async () => {
     const mediaBuffer = Buffer.from("test");
 

package/src/inbound/send-api.ts

@@ -5,6 +5,7 @@ import type {
   WAPresence,
 } from "@whiskeysockets/baileys";
 import { recordChannelActivity } from "openclaw/plugin-sdk/channel-activity-runtime";
+import { isWhatsAppNewsletterJid } from "../normalize.js";
 import { buildQuotedMessageOptions } from "../quoted-message.js";
 import { toWhatsappJid } from "../text-runtime.js";
 import {
@@ -135,6 +136,9 @@ export function createWebSendApi(params: {
     },
     sendComposingTo: async (to: string): Promise<void> => {
       const jid = toWhatsappJid(to);
+      if (isWhatsAppNewsletterJid(jid)) {
+        return;
+      }
       await params.sock.sendPresenceUpdate("composing", jid);
     },
   } as const;

package/src/normalize-target.ts

@@ -5,6 +5,7 @@ const WHATSAPP_USER_JID_RE = /^(\d+)(?::\d+)?@s\.whatsapp\.net$/i;
 const WHATSAPP_LEGACY_USER_JID_RE = /^(\d+)@c\.us$/i;
 const WHATSAPP_LID_RE = /^(\d+)@lid$/i;
 const NON_WHATSAPP_PROVIDER_PREFIX_RE = /^[a-z][a-z0-9-]*:/i;
+const WHATSAPP_NEWSLETTER_JID_RE = /^([0-9]+)@newsletter$/i;
 
 function stripWhatsAppTargetPrefixes(value: string): string {
   let candidate = value.trim();
@@ -30,6 +31,11 @@ export function isWhatsAppGroupJid(value: string): boolean {
   return /^[0-9]+(-[0-9]+)*$/.test(localPart);
 }
 
+export function isWhatsAppNewsletterJid(value: string): boolean {
+  const candidate = stripWhatsAppTargetPrefixes(value);
+  return WHATSAPP_NEWSLETTER_JID_RE.test(candidate);
+}
+
 export function isWhatsAppUserTarget(value: string): boolean {
   const candidate = stripWhatsAppTargetPrefixes(value);
   return (
@@ -64,6 +70,10 @@ export function normalizeWhatsAppTarget(value: string): string | null {
     const localPart = candidate.slice(0, candidate.length - "@g.us".length);
     return `${localPart}@g.us`;
   }
+  if (isWhatsAppNewsletterJid(candidate)) {
+    const match = candidate.match(WHATSAPP_NEWSLETTER_JID_RE);
+    return match ? `${match[1]}@newsletter` : null;
+  }
   if (isWhatsAppUserTarget(candidate)) {
     const phone = extractUserJidPhone(candidate);
     if (!phone) {
@@ -106,6 +116,7 @@ export function looksLikeWhatsAppTargetId(raw: string): boolean {
   return (
     /^whatsapp:/i.test(trimmed) ||
     isWhatsAppGroupJid(trimmed) ||
+    isWhatsAppNewsletterJid(trimmed) ||
     isWhatsAppUserTarget(trimmed) ||
     normalizeWhatsAppTarget(trimmed) !== null
   );

package/src/normalize.ts

@@ -2,5 +2,6 @@ export {
   looksLikeWhatsAppTargetId,
   normalizeWhatsAppMessagingTarget,
   isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
   normalizeWhatsAppTarget,
 } from "./normalize-target.js";

package/src/resolve-outbound-target.test.ts

@@ -130,6 +130,29 @@ describe("resolveWhatsAppOutboundTarget", () => {
     });
   });
 
+  describe("newsletter JID handling", () => {
+    it("returns success for valid newsletter JID without applying DM allowFrom", () => {
+      vi.mocked(normalize.normalizeWhatsAppTarget).mockReturnValueOnce(
+        "120363123456789@newsletter",
+      );
+      vi.mocked(normalize.isWhatsAppGroupJid).mockReturnValueOnce(false);
+      vi.mocked(normalize.isWhatsAppNewsletterJid).mockReturnValueOnce(true);
+
+      expectResolutionOk(
+        {
+          to: "120363123456789@newsletter",
+          allowFrom: [SECONDARY_TARGET],
+          mode: "implicit",
+        },
+        "120363123456789@newsletter",
+      );
+      expect(vi.mocked(normalize.normalizeWhatsAppTarget)).toHaveBeenCalledOnce();
+      expect(vi.mocked(normalize.normalizeWhatsAppTarget)).toHaveBeenCalledWith(
+        "120363123456789@newsletter",
+      );
+    });
+  });
+
   describe("implicit/heartbeat mode with allowList", () => {
     it("allows message when wildcard is present", () => {
       mockNormalizedDirectMessage(PRIMARY_TARGET, PRIMARY_TARGET);
@@ -154,14 +177,14 @@ describe("resolveWhatsAppOutboundTarget", () => {
           allowFrom: [SECONDARY_TARGET],
           mode: "implicit",
         },
-        `Target "${SECONDARY_TARGET}" is not listed in the configured WhatsApp allowFrom policy.`,
+        `Target "${PRIMARY_TARGET}" is not listed in the configured WhatsApp allowFrom policy.`,
       );
     });
 
     it("uses the normalized target in the allowFrom error message", () => {
       vi.mocked(normalize.normalizeWhatsAppTarget)
-        .mockReturnValueOnce(SECONDARY_TARGET)
-        .mockReturnValueOnce(PRIMARY_TARGET);
+        .mockReturnValueOnce(PRIMARY_TARGET)
+        .mockReturnValueOnce(SECONDARY_TARGET);
       vi.mocked(normalize.isWhatsAppGroupJid).mockReturnValueOnce(false);
 
       expectResolutionErrorMessage(
@@ -189,8 +212,8 @@ describe("resolveWhatsAppOutboundTarget", () => {
 
     it("filters out invalid normalized entries from allowList", () => {
       vi.mocked(normalize.normalizeWhatsAppTarget)
-        .mockReturnValueOnce(null)
         .mockReturnValueOnce("+11234567890")
+        .mockReturnValueOnce(null)
         .mockReturnValueOnce("+11234567890");
       vi.mocked(normalize.isWhatsAppGroupJid).mockReturnValueOnce(false);
 

package/src/resolve-outbound-target.ts

@@ -1,5 +1,9 @@
 import { missingTargetError } from "openclaw/plugin-sdk/channel-feedback";
-import { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "./normalize-target.js";
+import {
+  isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
+  normalizeWhatsAppTarget,
+} from "./normalize-target.js";
 
 export type WhatsAppOutboundTargetResolution =
   | { ok: true; to: string }
@@ -15,6 +19,24 @@ export function resolveWhatsAppOutboundTarget(params: {
   mode: string | null | undefined;
 }): WhatsAppOutboundTargetResolution {
   const trimmed = params.to?.trim() ?? "";
+  if (!trimmed) {
+    return {
+      ok: false,
+      error: missingTargetError("WhatsApp", "<E.164|group JID|newsletter JID>"),
+    };
+  }
+
+  const normalizedTo = normalizeWhatsAppTarget(trimmed);
+  if (!normalizedTo) {
+    return {
+      ok: false,
+      error: missingTargetError("WhatsApp", "<E.164|group JID|newsletter JID>"),
+    };
+  }
+  if (isWhatsAppGroupJid(normalizedTo) || isWhatsAppNewsletterJid(normalizedTo)) {
+    return { ok: true, to: normalizedTo };
+  }
+
   const allowListRaw = (params.allowFrom ?? [])
     .map((entry) => String(entry).trim())
     .filter(Boolean);
@@ -23,32 +45,14 @@ export function resolveWhatsAppOutboundTarget(params: {
     .filter((entry) => entry !== "*")
     .map((entry) => normalizeWhatsAppTarget(entry))
     .filter((entry): entry is string => Boolean(entry));
-
-  if (trimmed) {
-    const normalizedTo = normalizeWhatsAppTarget(trimmed);
-    if (!normalizedTo) {
-      return {
-        ok: false,
-        error: missingTargetError("WhatsApp", "<E.164|group JID>"),
-      };
-    }
-    if (isWhatsAppGroupJid(normalizedTo)) {
-      return { ok: true, to: normalizedTo };
-    }
-    if (hasWildcard || allowList.length === 0) {
-      return { ok: true, to: normalizedTo };
-    }
-    if (allowList.includes(normalizedTo)) {
-      return { ok: true, to: normalizedTo };
-    }
-    return {
-      ok: false,
-      error: whatsappAllowFromPolicyError(normalizedTo),
-    };
+  if (hasWildcard || allowList.length === 0) {
+    return { ok: true, to: normalizedTo };
+  }
+  if (allowList.includes(normalizedTo)) {
+    return { ok: true, to: normalizedTo };
   }
-
   return {
     ok: false,
-    error: missingTargetError("WhatsApp", "<E.164|group JID>"),
+    error: whatsappAllowFromPolicyError(normalizedTo),
   };
 }

package/src/resolve-target.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
   looksLikeWhatsAppTargetId,
   isWhatsAppUserTarget,
   normalizeWhatsAppMessagingTarget,
@@ -16,6 +17,15 @@ describe("normalizeWhatsAppTarget", () => {
     );
   });
 
+  it("preserves newsletter JIDs", () => {
+    expect(normalizeWhatsAppTarget("120363401234567890@newsletter")).toBe(
+      "120363401234567890@newsletter",
+    );
+    expect(normalizeWhatsAppTarget("WhatsApp:120363401234567890@NEWSLETTER")).toBe(
+      "120363401234567890@newsletter",
+    );
+  });
+
   it("normalizes direct JIDs to E.164", () => {
     expect(normalizeWhatsAppTarget("1555123@s.whatsapp.net")).toBe("+1555123");
   });
@@ -40,6 +50,7 @@ describe("normalizeWhatsAppTarget", () => {
     expect(normalizeWhatsAppTarget("group:123456789-987654321@g.us")).toBeNull();
     expect(normalizeWhatsAppTarget(" WhatsApp:Group:123456789-987654321@G.US ")).toBeNull();
     expect(normalizeWhatsAppTarget("abc@s.whatsapp.net")).toBeNull();
+    expect(normalizeWhatsAppTarget("abc@newsletter")).toBeNull();
   });
 
   it("rejects non-WhatsApp provider-prefixed phone-like targets", () => {
@@ -68,6 +79,17 @@ describe("isWhatsAppUserTarget", () => {
   });
 });
 
+describe("isWhatsAppNewsletterJid", () => {
+  it("detects newsletter JIDs with or without prefixes", () => {
+    expect(isWhatsAppNewsletterJid("120363401234567890@newsletter")).toBe(true);
+    expect(isWhatsAppNewsletterJid("whatsapp:120363401234567890@newsletter")).toBe(true);
+    expect(isWhatsAppNewsletterJid("120363401234567890@NEWSLETTER")).toBe(true);
+    expect(isWhatsAppNewsletterJid("abc@newsletter")).toBe(false);
+    expect(isWhatsAppNewsletterJid("120363401234567890@g.us")).toBe(false);
+    expect(isWhatsAppNewsletterJid("+1555123")).toBe(false);
+  });
+});
+
 describe("isWhatsAppGroupJid", () => {
   it("detects group JIDs with or without prefixes", () => {
     expect(isWhatsAppGroupJid("120363401234567890@g.us")).toBe(true);
@@ -91,6 +113,7 @@ describe("looksLikeWhatsAppTargetId", () => {
   it("detects common WhatsApp target forms", () => {
     expect(looksLikeWhatsAppTargetId("whatsapp:+15555550123")).toBe(true);
     expect(looksLikeWhatsAppTargetId("15555550123@c.us")).toBe(true);
+    expect(looksLikeWhatsAppTargetId("120363401234567890@newsletter")).toBe(true);
     expect(looksLikeWhatsAppTargetId("+15555550123")).toBe(true);
     expect(looksLikeWhatsAppTargetId("")).toBe(false);
   });

package/src/send.test.ts

@@ -144,6 +144,25 @@ describe("web outbound", () => {
     expect(sendMessage).toHaveBeenCalledWith("+1555", "hi", undefined, undefined);
   });
 
+  it("sends newsletter messages via the active listener without composing presence", async () => {
+    const result = await sendMessageWhatsApp("120363401234567890@newsletter", "hi", {
+      verbose: false,
+      cfg: WHATSAPP_TEST_CFG,
+    });
+
+    expect(result).toEqual({
+      messageId: "msg123",
+      toJid: "120363401234567890@newsletter",
+    });
+    expect(sendComposingTo).not.toHaveBeenCalled();
+    expect(sendMessage).toHaveBeenCalledWith(
+      "120363401234567890@newsletter",
+      "hi",
+      undefined,
+      undefined,
+    );
+  });
+
   it("uses configured defaultAccount when outbound accountId is omitted", async () => {
     hoisted.controllerListeners.clear();
     hoisted.controllerListeners.set("work", {

package/src/send.ts

@@ -16,6 +16,7 @@ import {
 } from "./accounts.js";
 import { getRegisteredWhatsAppConnectionController } from "./connection-controller-registry.js";
 import type { ActiveWebListener, ActiveWebSendOptions } from "./inbound/types.js";
+import { isWhatsAppNewsletterJid } from "./normalize.js";
 import {
   normalizeWhatsAppPayloadText,
   prepareWhatsAppOutboundMedia,
@@ -142,7 +143,9 @@ export async function sendMessageWhatsApp(
     }
     outboundLog.info(`Sending message -> ${redactedJid}${primaryMediaUrl ? " (media)" : ""}`);
     logger.info({ jid: redactedJid, hasMedia: Boolean(primaryMediaUrl) }, "sending message");
-    await active.sendComposingTo(to);
+    if (!isWhatsAppNewsletterJid(jid)) {
+      await active.sendComposingTo(to);
+    }
     const hasExplicitAccountId = Boolean(options.accountId?.trim());
     const accountId = hasExplicitAccountId ? resolvedAccountId : undefined;
     const sendOptions: ActiveWebSendOptions | undefined =
@@ -192,7 +195,9 @@ export async function sendTypingWhatsApp(
     cfg,
     accountId: options.accountId,
   });
-  await active.sendComposingTo(to);
+  if (!isWhatsAppNewsletterJid(toWhatsappJid(to))) {
+    await active.sendComposingTo(to);
+  }
 }
 
 export async function sendReactionWhatsApp(

package/src/session-route.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { resolveWhatsAppOutboundSessionRoute } from "./session-route.js";
+
+describe("resolveWhatsAppOutboundSessionRoute", () => {
+  it("routes newsletter JIDs as channel sessions", () => {
+    const route = resolveWhatsAppOutboundSessionRoute({
+      cfg: {},
+      agentId: "main",
+      target: "120363401234567890@newsletter",
+    });
+
+    expect(route).toMatchObject({
+      sessionKey: "agent:main:whatsapp:channel:120363401234567890@newsletter",
+      baseSessionKey: "agent:main:whatsapp:channel:120363401234567890@newsletter",
+      peer: {
+        kind: "channel",
+        id: "120363401234567890@newsletter",
+      },
+      chatType: "channel",
+      from: "120363401234567890@newsletter",
+      to: "120363401234567890@newsletter",
+    });
+  });
+
+  it("keeps direct user targets on direct session semantics", () => {
+    const route = resolveWhatsAppOutboundSessionRoute({
+      cfg: { session: { dmScope: "per-channel-peer" } },
+      agentId: "main",
+      target: "+15551234567",
+    });
+
+    expect(route).toMatchObject({
+      sessionKey: "agent:main:whatsapp:direct:+15551234567",
+      peer: {
+        kind: "direct",
+        id: "+15551234567",
+      },
+      chatType: "direct",
+    });
+  });
+});

package/src/session-route.ts

@@ -2,7 +2,11 @@ import {
   buildChannelOutboundSessionRoute,
   type ChannelOutboundSessionRouteParams,
 } from "openclaw/plugin-sdk/core";
-import { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "./normalize.js";
+import {
+  isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
+  normalizeWhatsAppTarget,
+} from "./normalize.js";
 
 export function resolveWhatsAppOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
   const normalized = normalizeWhatsAppTarget(params.target);
@@ -10,16 +14,18 @@ export function resolveWhatsAppOutboundSessionRoute(params: ChannelOutboundSessi
     return null;
   }
   const isGroup = isWhatsAppGroupJid(normalized);
+  const isNewsletter = isWhatsAppNewsletterJid(normalized);
+  const chatType = isGroup ? "group" : isNewsletter ? "channel" : "direct";
   return buildChannelOutboundSessionRoute({
     cfg: params.cfg,
     agentId: params.agentId,
     channel: "whatsapp",
     accountId: params.accountId,
     peer: {
-      kind: isGroup ? "group" : "direct",
+      kind: chatType,
       id: normalized,
     },
-    chatType: isGroup ? "group" : "direct",
+    chatType,
     from: normalized,
     to: normalized,
   });

package/src/shared.ts

@@ -208,7 +208,7 @@ export function createWhatsAppPluginBase(params: {
     },
     setupWizard: params.setupWizard,
     capabilities: {
-      chatTypes: ["direct", "group"],
+      chatTypes: ["direct", "group", "channel"],
       polls: true,
       reactions: true,
       media: true,