@openclaw/whatsapp 2026.5.2 → 2026.5.3-beta.2

package/src/send.ts

@@ -1,292 +0,0 @@
-import { formatCliCommand } from "openclaw/plugin-sdk/cli-runtime";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import { generateSecureUuid } from "openclaw/plugin-sdk/core";
-import { redactIdentifier } from "openclaw/plugin-sdk/logging-core";
-import {
-  convertMarkdownTables,
-  resolveMarkdownTableMode,
-} from "openclaw/plugin-sdk/markdown-table-runtime";
-import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
-import { normalizePollInput, type PollInput } from "openclaw/plugin-sdk/poll-runtime";
-import { createSubsystemLogger, getChildLogger } from "openclaw/plugin-sdk/runtime-env";
-import {
-  resolveDefaultWhatsAppAccountId,
-  resolveWhatsAppAccount,
-  resolveWhatsAppMediaMaxBytes,
-} 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,
-  resolveWhatsAppOutboundMediaUrls,
-} from "./outbound-media-contract.js";
-import { loadOutboundMediaFromUrl } from "./outbound-media.runtime.js";
-import { markdownToWhatsApp, toWhatsappJid } from "./text-runtime.js";
-
-const outboundLog = createSubsystemLogger("gateway/channels/whatsapp").child("outbound");
-
-function resolveOutboundWhatsAppAccountId(params: {
-  cfg: OpenClawConfig;
-  accountId?: string;
-}): string | undefined {
-  const explicitAccountId = params.accountId?.trim();
-  if (explicitAccountId) {
-    return explicitAccountId;
-  }
-  return resolveDefaultWhatsAppAccountId(params.cfg);
-}
-
-function requireOutboundActiveWebListener(params: { cfg: OpenClawConfig; accountId?: string }): {
-  accountId: string;
-  listener: ActiveWebListener;
-} {
-  const accountId = resolveOutboundWhatsAppAccountId(params);
-  const resolvedAccountId = accountId ?? resolveDefaultWhatsAppAccountId(params.cfg);
-  const listener =
-    getRegisteredWhatsAppConnectionController(resolvedAccountId)?.getActiveListener() ?? null;
-  if (!listener) {
-    throw new Error(
-      `No active WhatsApp Web listener (account: ${resolvedAccountId}). Start the gateway, then link WhatsApp with: ${formatCliCommand(`openclaw channels login --channel whatsapp --account ${resolvedAccountId}`)}.`,
-    );
-  }
-  return { accountId: resolvedAccountId, listener };
-}
-
-export async function sendMessageWhatsApp(
-  to: string,
-  body: string,
-  options: {
-    verbose: boolean;
-    cfg: OpenClawConfig;
-    mediaUrl?: string;
-    mediaUrls?: readonly string[];
-    mediaAccess?: {
-      localRoots?: readonly string[];
-      readFile?: (filePath: string) => Promise<Buffer>;
-    };
-    mediaLocalRoots?: readonly string[];
-    mediaReadFile?: (filePath: string) => Promise<Buffer>;
-    gifPlayback?: boolean;
-    audioAsVoice?: boolean;
-    accountId?: string;
-    quotedMessageKey?: {
-      id: string;
-      remoteJid: string;
-      fromMe: boolean;
-      participant?: string;
-      messageText?: string;
-    };
-    preserveLeadingWhitespace?: boolean;
-  },
-): Promise<{ messageId: string; toJid: string }> {
-  let text = options.preserveLeadingWhitespace ? body : normalizeWhatsAppPayloadText(body);
-  const jid = toWhatsappJid(to);
-  const mediaUrls = resolveWhatsAppOutboundMediaUrls(options);
-  const primaryMediaUrl = mediaUrls[0];
-  if (!text && !primaryMediaUrl) {
-    return { messageId: "", toJid: jid };
-  }
-  const correlationId = generateSecureUuid();
-  const startedAt = Date.now();
-  const cfg = requireRuntimeConfig(options.cfg, "WhatsApp send");
-  const { listener: active, accountId: resolvedAccountId } = requireOutboundActiveWebListener({
-    cfg,
-    accountId: options.accountId,
-  });
-  const account = resolveWhatsAppAccount({
-    cfg,
-    accountId: resolvedAccountId ?? options.accountId,
-  });
-  const tableMode = resolveMarkdownTableMode({
-    cfg,
-    channel: "whatsapp",
-    accountId: resolvedAccountId ?? options.accountId,
-  });
-  text = convertMarkdownTables(text ?? "", tableMode);
-  text = markdownToWhatsApp(text);
-  const redactedTo = redactIdentifier(to);
-  const logger = getChildLogger({
-    module: "web-outbound",
-    correlationId,
-    to: redactedTo,
-  });
-  try {
-    const redactedJid = redactIdentifier(jid);
-    let mediaBuffer: Buffer | undefined;
-    let mediaType: string | undefined;
-    let documentFileName: string | undefined;
-    let visibleTextAfterVoice: string | undefined;
-    if (primaryMediaUrl) {
-      const media = await prepareWhatsAppOutboundMedia(
-        await loadOutboundMediaFromUrl(primaryMediaUrl, {
-          maxBytes: resolveWhatsAppMediaMaxBytes(account),
-          mediaAccess: options.mediaAccess,
-          mediaLocalRoots: options.mediaLocalRoots,
-          mediaReadFile: options.mediaReadFile,
-        }),
-        primaryMediaUrl,
-      );
-      const caption = text || undefined;
-      mediaBuffer = media.buffer;
-      mediaType = media.mimetype;
-      if (media.kind === "audio" && caption) {
-        visibleTextAfterVoice = caption;
-        text = "";
-      } else if (media.kind === "document") {
-        text = caption ?? "";
-        documentFileName = media.fileName;
-      } else {
-        text = caption ?? "";
-      }
-    }
-    outboundLog.info(`Sending message -> ${redactedJid}${primaryMediaUrl ? " (media)" : ""}`);
-    logger.info({ jid: redactedJid, hasMedia: Boolean(primaryMediaUrl) }, "sending message");
-    if (!isWhatsAppNewsletterJid(jid)) {
-      await active.sendComposingTo(to);
-    }
-    const hasExplicitAccountId = Boolean(options.accountId?.trim());
-    const accountId = hasExplicitAccountId ? resolvedAccountId : undefined;
-    const sendOptions: ActiveWebSendOptions | undefined =
-      options.gifPlayback || accountId || documentFileName || options.quotedMessageKey
-        ? {
-            ...(options.gifPlayback ? { gifPlayback: true } : {}),
-            ...(documentFileName ? { fileName: documentFileName } : {}),
-            ...(options.quotedMessageKey ? { quotedMessageKey: options.quotedMessageKey } : {}),
-            accountId,
-          }
-        : undefined;
-    const result = sendOptions
-      ? await active.sendMessage(to, text, mediaBuffer, mediaType, sendOptions)
-      : await active.sendMessage(to, text, mediaBuffer, mediaType);
-    if (visibleTextAfterVoice) {
-      if (sendOptions) {
-        await active.sendMessage(to, visibleTextAfterVoice, undefined, undefined, sendOptions);
-      } else {
-        await active.sendMessage(to, visibleTextAfterVoice, undefined, undefined);
-      }
-    }
-    const messageId = (result as { messageId?: string })?.messageId ?? "unknown";
-    const durationMs = Date.now() - startedAt;
-    outboundLog.info(
-      `Sent message ${messageId} -> ${redactedJid}${primaryMediaUrl ? " (media)" : ""} (${durationMs}ms)`,
-    );
-    logger.info({ jid: redactedJid, messageId }, "sent message");
-    return { messageId, toJid: jid };
-  } catch (err) {
-    logger.error(
-      { err: String(err), to: redactedTo, hasMedia: Boolean(primaryMediaUrl) },
-      "failed to send via web session",
-    );
-    throw err;
-  }
-}
-
-export async function sendTypingWhatsApp(
-  to: string,
-  options: {
-    cfg: OpenClawConfig;
-    accountId?: string;
-  },
-): Promise<void> {
-  const cfg = requireRuntimeConfig(options.cfg, "WhatsApp typing send");
-  const { listener: active } = requireOutboundActiveWebListener({
-    cfg,
-    accountId: options.accountId,
-  });
-  if (!isWhatsAppNewsletterJid(toWhatsappJid(to))) {
-    await active.sendComposingTo(to);
-  }
-}
-
-export async function sendReactionWhatsApp(
-  chatJid: string,
-  messageId: string,
-  emoji: string,
-  options: {
-    verbose: boolean;
-    fromMe?: boolean;
-    participant?: string;
-    accountId?: string;
-    cfg: OpenClawConfig;
-  },
-): Promise<void> {
-  const correlationId = generateSecureUuid();
-  const cfg = requireRuntimeConfig(options.cfg, "WhatsApp reaction");
-  const { listener: active } = requireOutboundActiveWebListener({
-    cfg,
-    accountId: options.accountId,
-  });
-  const redactedChatJid = redactIdentifier(chatJid);
-  const logger = getChildLogger({
-    module: "web-outbound",
-    correlationId,
-    chatJid: redactedChatJid,
-    messageId,
-  });
-  try {
-    const jid = toWhatsappJid(chatJid);
-    const redactedJid = redactIdentifier(jid);
-    outboundLog.info(`Sending reaction "${emoji}" -> message ${messageId}`);
-    logger.info({ chatJid: redactedJid, messageId, emoji }, "sending reaction");
-    await active.sendReaction(
-      chatJid,
-      messageId,
-      emoji,
-      options.fromMe ?? false,
-      options.participant,
-    );
-    outboundLog.info(`Sent reaction "${emoji}" -> message ${messageId}`);
-    logger.info({ chatJid: redactedJid, messageId, emoji }, "sent reaction");
-  } catch (err) {
-    logger.error(
-      { err: String(err), chatJid: redactedChatJid, messageId, emoji },
-      "failed to send reaction via web session",
-    );
-    throw err;
-  }
-}
-
-export async function sendPollWhatsApp(
-  to: string,
-  poll: PollInput,
-  options: { verbose: boolean; accountId?: string; cfg: OpenClawConfig },
-): Promise<{ messageId: string; toJid: string }> {
-  const correlationId = generateSecureUuid();
-  const startedAt = Date.now();
-  const cfg = requireRuntimeConfig(options.cfg, "WhatsApp poll");
-  const { listener: active } = requireOutboundActiveWebListener({
-    cfg,
-    accountId: options.accountId,
-  });
-  const redactedTo = redactIdentifier(to);
-  const logger = getChildLogger({
-    module: "web-outbound",
-    correlationId,
-    to: redactedTo,
-  });
-  try {
-    const jid = toWhatsappJid(to);
-    const redactedJid = redactIdentifier(jid);
-    const normalized = normalizePollInput(poll, { maxOptions: 12 });
-    outboundLog.info(`Sending poll -> ${redactedJid}`);
-    logger.info(
-      {
-        jid: redactedJid,
-        optionCount: normalized.options.length,
-        maxSelections: normalized.maxSelections,
-      },
-      "sending poll",
-    );
-    const result = await active.sendPoll(to, normalized);
-    const messageId = (result as { messageId?: string })?.messageId ?? "unknown";
-    const durationMs = Date.now() - startedAt;
-    outboundLog.info(`Sent poll ${messageId} -> ${redactedJid} (${durationMs}ms)`);
-    logger.info({ jid: redactedJid, messageId }, "sent poll");
-    return { messageId, toJid: jid };
-  } catch (err) {
-    logger.error({ err: String(err), to: redactedTo }, "failed to send poll via web session");
-    throw err;
-  }
-}

package/src/session-contract.test.ts

@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  canonicalizeLegacySessionKey,
-  deriveLegacySessionChatType,
-  isLegacyGroupSessionKey,
-} from "./session-contract.js";
-
-describe("whatsapp legacy session contract", () => {
-  it("canonicalizes legacy WhatsApp group keys to channel-qualified agent keys", () => {
-    expect(canonicalizeLegacySessionKey({ key: "group:123@g.us", agentId: "main" })).toBe(
-      "agent:main:whatsapp:group:123@g.us",
-    );
-    expect(canonicalizeLegacySessionKey({ key: "123@g.us", agentId: "main" })).toBe(
-      "agent:main:whatsapp:group:123@g.us",
-    );
-    expect(canonicalizeLegacySessionKey({ key: "whatsapp:123@g.us", agentId: "main" })).toBe(
-      "agent:main:whatsapp:group:123@g.us",
-    );
-  });
-
-  it("does not claim generic non-WhatsApp group keys", () => {
-    expect(isLegacyGroupSessionKey("group:abc")).toBe(false);
-    expect(deriveLegacySessionChatType("group:abc")).toBeUndefined();
-    expect(canonicalizeLegacySessionKey({ key: "group:abc", agentId: "main" })).toBeNull();
-  });
-
-  it("derives chat type for legacy WhatsApp group keys", () => {
-    expect(deriveLegacySessionChatType("123@g.us")).toBe("group");
-    expect(deriveLegacySessionChatType("whatsapp:123@g.us")).toBe("group");
-  });
-});

package/src/session-contract.ts

@@ -1,43 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
-
-function extractLegacyWhatsAppGroupId(key: string): string | null {
-  const trimmed = key.trim();
-  if (!trimmed) {
-    return null;
-  }
-  const lower = normalizeLowercaseStringOrEmpty(trimmed);
-  if (trimmed.startsWith("group:")) {
-    const id = trimmed.slice("group:".length).trim();
-    return normalizeLowercaseStringOrEmpty(id).includes("@g.us") ? id : null;
-  }
-  if (!lower.includes("@g.us")) {
-    return null;
-  }
-  if (!trimmed.includes(":")) {
-    return trimmed;
-  }
-  if (lower.startsWith("whatsapp:") && !trimmed.includes(":group:")) {
-    const remainder = trimmed.slice("whatsapp:".length).trim();
-    const cleaned = remainder.replace(/^group:/i, "").trim();
-    return cleaned || null;
-  }
-  return null;
-}
-
-export function isLegacyGroupSessionKey(key: string): boolean {
-  return extractLegacyWhatsAppGroupId(key) !== null;
-}
-
-export function deriveLegacySessionChatType(key: string): "group" | undefined {
-  return isLegacyGroupSessionKey(key) ? "group" : undefined;
-}
-
-export function canonicalizeLegacySessionKey(params: {
-  key: string;
-  agentId: string;
-}): string | null {
-  const legacyGroupId = extractLegacyWhatsAppGroupId(params.key);
-  return legacyGroupId
-    ? `agent:${normalizeLowercaseStringOrEmpty(params.agentId)}:whatsapp:group:${normalizeLowercaseStringOrEmpty(legacyGroupId)}`
-    : null;
-}

package/src/session-errors.ts

@@ -1,125 +0,0 @@
-function safeStringify(value: unknown, limit = 800): string {
-  try {
-    const seen = new WeakSet();
-    const raw = JSON.stringify(
-      value,
-      (_key, v) => {
-        if (typeof v === "bigint") {
-          return v.toString();
-        }
-        if (typeof v === "function") {
-          const maybeName = (v as { name?: unknown }).name;
-          const name =
-            typeof maybeName === "string" && maybeName.length > 0 ? maybeName : "anonymous";
-          return `[Function ${name}]`;
-        }
-        if (typeof v === "object" && v) {
-          if (seen.has(v)) {
-            return "[Circular]";
-          }
-          seen.add(v);
-        }
-        return v;
-      },
-      2,
-    );
-    if (!raw) {
-      return String(value);
-    }
-    return raw.length > limit ? `${raw.slice(0, limit)}…` : raw;
-  } catch {
-    return String(value);
-  }
-}
-
-function extractBoomDetails(err: unknown): {
-  statusCode?: number;
-  error?: string;
-  message?: string;
-} | null {
-  if (!err || typeof err !== "object") {
-    return null;
-  }
-  const output = (err as { output?: unknown })?.output as
-    | { statusCode?: unknown; payload?: unknown }
-    | undefined;
-  if (!output || typeof output !== "object") {
-    return null;
-  }
-  const payload = (output as { payload?: unknown }).payload as
-    | { error?: unknown; message?: unknown; statusCode?: unknown }
-    | undefined;
-  const statusCode =
-    typeof (output as { statusCode?: unknown }).statusCode === "number"
-      ? ((output as { statusCode?: unknown }).statusCode as number)
-      : typeof payload?.statusCode === "number"
-        ? payload.statusCode
-        : undefined;
-  const error = typeof payload?.error === "string" ? payload.error : undefined;
-  const message = typeof payload?.message === "string" ? payload.message : undefined;
-  if (!statusCode && !error && !message) {
-    return null;
-  }
-  return { statusCode, error, message };
-}
-
-export function getStatusCode(err: unknown) {
-  return (
-    (err as { output?: { statusCode?: number } })?.output?.statusCode ??
-    (err as { status?: number })?.status ??
-    (err as { error?: { output?: { statusCode?: number } } })?.error?.output?.statusCode
-  );
-}
-
-export function formatError(err: unknown): string {
-  if (err instanceof Error) {
-    return err.message;
-  }
-  if (typeof err === "string") {
-    return err;
-  }
-  if (!err || typeof err !== "object") {
-    return String(err);
-  }
-
-  const boom =
-    extractBoomDetails(err) ??
-    extractBoomDetails((err as { error?: unknown })?.error) ??
-    extractBoomDetails((err as { lastDisconnect?: { error?: unknown } })?.lastDisconnect?.error);
-
-  const status = boom?.statusCode ?? getStatusCode(err);
-  const code = (err as { code?: unknown })?.code;
-  const codeText = typeof code === "string" || typeof code === "number" ? String(code) : undefined;
-
-  const messageCandidates = [
-    boom?.message,
-    typeof (err as { message?: unknown })?.message === "string"
-      ? ((err as { message?: unknown }).message as string)
-      : undefined,
-    typeof (err as { error?: { message?: unknown } })?.error?.message === "string"
-      ? ((err as { error?: { message?: unknown } }).error?.message as string)
-      : undefined,
-  ];
-  const message = messageCandidates.find((value): value is string =>
-    Boolean(value && value.trim().length > 0),
-  );
-
-  const pieces: string[] = [];
-  if (typeof status === "number") {
-    pieces.push(`status=${status}`);
-  }
-  if (boom?.error) {
-    pieces.push(boom.error);
-  }
-  if (message) {
-    pieces.push(message);
-  }
-  if (codeText) {
-    pieces.push(`code=${codeText}`);
-  }
-
-  if (pieces.length > 0) {
-    return pieces.join(" ");
-  }
-  return safeStringify(err);
-}

package/src/session-route.test.ts

@@ -1,41 +0,0 @@
-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

@@ -1,32 +0,0 @@
-import {
-  buildChannelOutboundSessionRoute,
-  type ChannelOutboundSessionRouteParams,
-} from "openclaw/plugin-sdk/core";
-import {
-  isWhatsAppGroupJid,
-  isWhatsAppNewsletterJid,
-  normalizeWhatsAppTarget,
-} from "./normalize.js";
-
-export function resolveWhatsAppOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
-  const normalized = normalizeWhatsAppTarget(params.target);
-  if (!normalized) {
-    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: chatType,
-      id: normalized,
-    },
-    chatType,
-    from: normalized,
-    to: normalized,
-  });
-}

package/src/session.runtime.ts

@@ -1,8 +0,0 @@
-export {
-  BufferJSON,
-  DisconnectReason,
-  fetchLatestBaileysVersion,
-  makeCacheableSignalKeyStore,
-  makeWASocket,
-  useMultiFileAuthState,
-} from "@whiskeysockets/baileys";