@openclaw/whatsapp 2026.5.2 → 2026.5.3-beta.2

package/src/inbound/runtime-api.ts

@@ -1,7 +0,0 @@
-export {
-  DisconnectReason,
-  downloadMediaMessage,
-  isJidGroup,
-  normalizeMessageContent,
-} from "@whiskeysockets/baileys";
-export { saveMediaBuffer } from "./save-media.runtime.js";

package/src/inbound/save-media.runtime.ts

@@ -1 +0,0 @@
-export { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";

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

@@ -1,319 +0,0 @@
-import type {
-  AnyMessageContent,
-  MiscMessageGenerationOptions,
-  WAMessage,
-} from "@whiskeysockets/baileys";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { createWebSendApi } from "./send-api.js";
-
-const recordChannelActivity = vi.hoisted(() => vi.fn());
-
-vi.mock("openclaw/plugin-sdk/channel-activity-runtime", async () => {
-  const actual = await vi.importActual<
-    typeof import("openclaw/plugin-sdk/channel-activity-runtime")
-  >("openclaw/plugin-sdk/channel-activity-runtime");
-  return {
-    ...actual,
-    recordChannelActivity: (...args: unknown[]) => recordChannelActivity(...args),
-  };
-});
-
-describe("createWebSendApi", () => {
-  const sendMessage = vi.fn(
-    async (
-      _jid: string,
-      _content: AnyMessageContent,
-      _options?: MiscMessageGenerationOptions,
-    ): Promise<WAMessage | undefined> => ({ key: { id: "msg-1" } }) as WAMessage,
-  );
-  const sendPresenceUpdate = vi.fn(async () => {});
-  let api: ReturnType<typeof createWebSendApi>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    api = createWebSendApi({
-      sock: { sendMessage, sendPresenceUpdate },
-      defaultAccountId: "main",
-    });
-  });
-
-  it("uses sendOptions fileName for outbound documents", async () => {
-    const payload = Buffer.from("pdf");
-    await api.sendMessage("+1555", "doc", payload, "application/pdf", { fileName: "invoice.pdf" });
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        document: payload,
-        fileName: "invoice.pdf",
-        caption: "doc",
-        mimetype: "application/pdf",
-      }),
-    );
-    expect(recordChannelActivity).toHaveBeenCalledWith({
-      channel: "whatsapp",
-      accountId: "main",
-      direction: "outbound",
-    });
-  });
-
-  it("falls back to default document filename when fileName is absent", async () => {
-    const payload = Buffer.from("pdf");
-    await api.sendMessage("+1555", "doc", payload, "application/pdf");
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        document: payload,
-        fileName: "file",
-        caption: "doc",
-        mimetype: "application/pdf",
-      }),
-    );
-  });
-
-  it("sends plain text messages", async () => {
-    const res = await api.sendMessage("+1555", "hello");
-    expect(sendMessage).toHaveBeenCalledWith("1555@s.whatsapp.net", { text: "hello" });
-    expect(res).toMatchObject({
-      kind: "text",
-      messageId: "msg-1",
-      messageIds: ["msg-1"],
-      providerAccepted: true,
-    });
-    expect(recordChannelActivity).toHaveBeenCalledWith({
-      channel: "whatsapp",
-      accountId: "main",
-      direction: "outbound",
-    });
-  });
-
-  it("supports image media with caption", async () => {
-    const payload = Buffer.from("img");
-    await api.sendMessage("+1555", "cap", payload, "image/jpeg");
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        image: payload,
-        caption: "cap",
-        mimetype: "image/jpeg",
-      }),
-    );
-  });
-
-  it("supports audio as push-to-talk voice note", async () => {
-    const payload = Buffer.from("aud");
-    await api.sendMessage("+1555", "", payload, "audio/ogg", { accountId: "alt" });
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        audio: payload,
-        ptt: true,
-        mimetype: "audio/ogg",
-      }),
-    );
-    expect(recordChannelActivity).toHaveBeenCalledWith({
-      channel: "whatsapp",
-      accountId: "alt",
-      direction: "outbound",
-    });
-  });
-
-  it("sends visible text separately from push-to-talk voice notes", async () => {
-    const payload = Buffer.from("aud");
-    sendMessage
-      .mockResolvedValueOnce({ key: { id: "voice-1" } })
-      .mockResolvedValueOnce({ key: { id: "voice-text-1" } });
-    const res = await api.sendMessage("+1555", "voice text", payload, "audio/ogg");
-    expect(sendMessage).toHaveBeenNthCalledWith(
-      1,
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        audio: payload,
-        ptt: true,
-        mimetype: "audio/ogg",
-      }),
-    );
-    expect(sendMessage).toHaveBeenNthCalledWith(2, "1555@s.whatsapp.net", {
-      text: "voice text",
-    });
-    expect(res).toMatchObject({
-      kind: "media",
-      messageId: "voice-1",
-      messageIds: ["voice-1", "voice-text-1"],
-      providerAccepted: true,
-    });
-  });
-
-  it("supports video media and gifPlayback option", async () => {
-    const payload = Buffer.from("vid");
-    await api.sendMessage("+1555", "cap", payload, "video/mp4", { gifPlayback: true });
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        video: payload,
-        caption: "cap",
-        mimetype: "video/mp4",
-        gifPlayback: true,
-      }),
-    );
-  });
-
-  it("falls back to unknown messageId if Baileys result does not expose key.id", async () => {
-    sendMessage.mockResolvedValueOnce({ key: {} as { id: string } });
-    const res = await api.sendMessage("+1555", "hello");
-    expect(res.messageId).toBe("unknown");
-  });
-
-  it("sends polls and records outbound activity", async () => {
-    const res = await api.sendPoll("+1555", {
-      question: "Q?",
-      options: ["a", "b"],
-      maxSelections: 2,
-    });
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        poll: { name: "Q?", values: ["a", "b"], selectableCount: 2 },
-      }),
-    );
-    expect(res.messageId).toBe("msg-1");
-    expect(recordChannelActivity).toHaveBeenCalledWith({
-      channel: "whatsapp",
-      accountId: "main",
-      direction: "outbound",
-    });
-  });
-
-  it("sends reactions with participant JID normalization", async () => {
-    const res = await api.sendReaction("+1555", "msg-2", "👍", false, "+1999");
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        react: {
-          text: "👍",
-          key: expect.objectContaining({
-            remoteJid: "1555@s.whatsapp.net",
-            id: "msg-2",
-            fromMe: false,
-            participant: "1999@s.whatsapp.net",
-          }),
-        },
-      }),
-    );
-    expect(res).toMatchObject({
-      kind: "reaction",
-      messageId: "msg-1",
-      providerAccepted: true,
-    });
-  });
-
-  it("reports provider-unaccepted sends when Baileys returns no message", async () => {
-    sendMessage.mockResolvedValueOnce(undefined);
-
-    const res = await api.sendMessage("+1555", "hello");
-
-    expect(res).toMatchObject({
-      kind: "text",
-      messageId: "unknown",
-      messageIds: [],
-      providerAccepted: false,
-    });
-  });
-
-  it("keeps direct-chat reactions without a participant key", async () => {
-    await api.sendReaction("+1555", "msg-2", "👍", false);
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      expect.objectContaining({
-        react: {
-          text: "👍",
-          key: expect.objectContaining({
-            remoteJid: "1555@s.whatsapp.net",
-            id: "msg-2",
-            fromMe: false,
-            participant: undefined,
-          }),
-        },
-      }),
-    );
-  });
-
-  it("preserves LID participants in reaction keys", async () => {
-    await api.sendReaction("12345@g.us", "msg-2", "👍", false, "123@lid");
-    expect(sendMessage).toHaveBeenCalledWith(
-      "12345@g.us",
-      expect.objectContaining({
-        react: {
-          text: "👍",
-          key: expect.objectContaining({
-            remoteJid: "12345@g.us",
-            id: "msg-2",
-            fromMe: false,
-            participant: "123@lid",
-          }),
-        },
-      }),
-    );
-  });
-
-  it("sends composing presence updates to the recipient JID", async () => {
-    await api.sendComposingTo("+1555");
-    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");
-
-    await api.sendMessage("123", "hello", mediaBuffer, undefined);
-
-    expect(sendMessage).toHaveBeenCalledWith(
-      "123@s.whatsapp.net",
-      expect.objectContaining({
-        document: mediaBuffer,
-        mimetype: "application/octet-stream",
-      }),
-    );
-  });
-
-  it("does not set mediaType when mediaBuffer is absent", async () => {
-    await api.sendMessage("123", "hello");
-
-    expect(sendMessage).toHaveBeenCalledWith("123@s.whatsapp.net", { text: "hello" });
-  });
-
-  it("preserves the quoted remoteJid provided by the outbound adapter", async () => {
-    await api.sendMessage("+1555", "hello", undefined, undefined, {
-      quotedMessageKey: {
-        id: "quoted-1",
-        remoteJid: "277038292303944@lid",
-        fromMe: false,
-        participant: "1234@s.whatsapp.net",
-        messageText: "quoted body",
-      },
-    });
-
-    expect(sendMessage).toHaveBeenCalledWith(
-      "1555@s.whatsapp.net",
-      { text: "hello" },
-      expect.objectContaining({
-        quoted: expect.objectContaining({
-          key: expect.objectContaining({
-            remoteJid: "277038292303944@lid",
-            id: "quoted-1",
-          }),
-        }),
-      }),
-    );
-  });
-});

package/src/inbound/send-api.ts

@@ -1,145 +0,0 @@
-import type {
-  AnyMessageContent,
-  MiscMessageGenerationOptions,
-  WAMessage,
-  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 {
-  combineWhatsAppSendResults,
-  normalizeWhatsAppSendResult,
-  type WhatsAppSendResult,
-} from "./send-result.js";
-import type { ActiveWebSendOptions } from "./types.js";
-
-function recordWhatsAppOutbound(accountId: string) {
-  recordChannelActivity({
-    channel: "whatsapp",
-    accountId,
-    direction: "outbound",
-  });
-}
-
-export function createWebSendApi(params: {
-  sock: {
-    sendMessage: (
-      jid: string,
-      content: AnyMessageContent,
-      options?: MiscMessageGenerationOptions,
-    ) => Promise<WAMessage | undefined>;
-    sendPresenceUpdate: (presence: WAPresence, jid?: string) => Promise<unknown>;
-  };
-  defaultAccountId: string;
-}) {
-  return {
-    sendMessage: async (
-      to: string,
-      text: string,
-      mediaBuffer?: Buffer,
-      mediaType?: string,
-      sendOptions?: ActiveWebSendOptions,
-    ): Promise<WhatsAppSendResult> => {
-      const jid = toWhatsappJid(to);
-      let payload: AnyMessageContent;
-      if (mediaBuffer) {
-        mediaType ??= "application/octet-stream";
-      }
-      if (mediaBuffer && mediaType) {
-        if (mediaType.startsWith("image/")) {
-          payload = {
-            image: mediaBuffer,
-            caption: text || undefined,
-            mimetype: mediaType,
-          };
-        } else if (mediaType.startsWith("audio/")) {
-          payload = { audio: mediaBuffer, ptt: true, mimetype: mediaType };
-        } else if (mediaType.startsWith("video/")) {
-          const gifPlayback = sendOptions?.gifPlayback;
-          payload = {
-            video: mediaBuffer,
-            caption: text || undefined,
-            mimetype: mediaType,
-            ...(gifPlayback ? { gifPlayback: true } : {}),
-          };
-        } else {
-          const fileName = sendOptions?.fileName?.trim() || "file";
-          payload = {
-            document: mediaBuffer,
-            fileName,
-            caption: text || undefined,
-            mimetype: mediaType,
-          };
-        }
-      } else {
-        payload = { text };
-      }
-      const quotedOpts = buildQuotedMessageOptions({
-        messageId: sendOptions?.quotedMessageKey?.id,
-        remoteJid: sendOptions?.quotedMessageKey?.remoteJid,
-        fromMe: sendOptions?.quotedMessageKey?.fromMe,
-        participant: sendOptions?.quotedMessageKey?.participant,
-        messageText: sendOptions?.quotedMessageKey?.messageText,
-      });
-      const result = quotedOpts
-        ? await params.sock.sendMessage(jid, payload, quotedOpts)
-        : await params.sock.sendMessage(jid, payload);
-      const results = [normalizeWhatsAppSendResult(result, mediaBuffer ? "media" : "text")];
-      if (mediaBuffer && mediaType?.startsWith("audio/") && text.trim()) {
-        const textPayload: AnyMessageContent = { text };
-        const textResult = quotedOpts
-          ? await params.sock.sendMessage(jid, textPayload, quotedOpts)
-          : await params.sock.sendMessage(jid, textPayload);
-        results.push(normalizeWhatsAppSendResult(textResult, "text"));
-      }
-      const accountId = sendOptions?.accountId ?? params.defaultAccountId;
-      recordWhatsAppOutbound(accountId);
-      return combineWhatsAppSendResults(mediaBuffer ? "media" : "text", results);
-    },
-    sendPoll: async (
-      to: string,
-      poll: { question: string; options: string[]; maxSelections?: number },
-    ): Promise<WhatsAppSendResult> => {
-      const jid = toWhatsappJid(to);
-      const result = await params.sock.sendMessage(jid, {
-        poll: {
-          name: poll.question,
-          values: poll.options,
-          selectableCount: poll.maxSelections ?? 1,
-        },
-      } as AnyMessageContent);
-      recordWhatsAppOutbound(params.defaultAccountId);
-      return normalizeWhatsAppSendResult(result, "poll");
-    },
-    sendReaction: async (
-      chatJid: string,
-      messageId: string,
-      emoji: string,
-      fromMe: boolean,
-      participant?: string,
-    ): Promise<WhatsAppSendResult> => {
-      const jid = toWhatsappJid(chatJid);
-      const result = await params.sock.sendMessage(jid, {
-        react: {
-          text: emoji,
-          key: {
-            remoteJid: jid,
-            id: messageId,
-            fromMe,
-            participant: participant ? toWhatsappJid(participant) : undefined,
-          },
-        },
-      } as AnyMessageContent);
-      return normalizeWhatsAppSendResult(result, "reaction");
-    },
-    sendComposingTo: async (to: string): Promise<void> => {
-      const jid = toWhatsappJid(to);
-      if (isWhatsAppNewsletterJid(jid)) {
-        return;
-      }
-      await params.sock.sendPresenceUpdate("composing", jid);
-    },
-  } as const;
-}

package/src/inbound/send-result.ts

@@ -1,61 +0,0 @@
-import type { WAMessage, WAMessageKey } from "@whiskeysockets/baileys";
-
-export type WhatsAppSendKind = "media" | "poll" | "reaction" | "text";
-
-type WhatsAppSendKey = Omit<
-  Pick<WAMessageKey, "fromMe" | "id" | "participant" | "remoteJid">,
-  "id"
-> & {
-  id: string;
-};
-
-export type WhatsAppSendResult = {
-  kind: WhatsAppSendKind;
-  messageId: string;
-  messageIds: string[];
-  keys: WhatsAppSendKey[];
-  providerAccepted: boolean;
-};
-
-function normalizeKey(key: WAMessageKey | undefined): WhatsAppSendKey | undefined {
-  const id = typeof key?.id === "string" ? key.id.trim() : "";
-  if (!id) {
-    return undefined;
-  }
-  return {
-    id,
-    remoteJid: key?.remoteJid,
-    fromMe: key?.fromMe,
-    participant: key?.participant,
-  };
-}
-
-export function normalizeWhatsAppSendResult(
-  result: WAMessage | undefined,
-  kind: WhatsAppSendKind,
-): WhatsAppSendResult {
-  const key = normalizeKey(result?.key);
-  const messageId = key?.id ?? "unknown";
-  return {
-    kind,
-    messageId,
-    messageIds: key ? [key.id] : [],
-    keys: key ? [key] : [],
-    providerAccepted: Boolean(key),
-  };
-}
-
-export function combineWhatsAppSendResults(
-  kind: WhatsAppSendKind,
-  results: readonly WhatsAppSendResult[],
-): WhatsAppSendResult {
-  const messageIds = [...new Set(results.flatMap((result) => result.messageIds))];
-  const keys = results.flatMap((result) => result.keys);
-  return {
-    kind,
-    messageId: messageIds[0] ?? "unknown",
-    messageIds,
-    keys,
-    providerAccepted: results.some((result) => result.providerAccepted),
-  };
-}

package/src/inbound/types.ts

@@ -1,106 +0,0 @@
-import type { AnyMessageContent, MiscMessageGenerationOptions } from "@whiskeysockets/baileys";
-import type { NormalizedLocation } from "openclaw/plugin-sdk/channel-inbound";
-import type { PollInput } from "openclaw/plugin-sdk/poll-runtime";
-import type { WhatsAppIdentity, WhatsAppReplyContext, WhatsAppSelfIdentity } from "../identity.js";
-import type { WhatsAppSendResult } from "./send-result.js";
-
-export type WebListenerCloseReason = {
-  status?: number;
-  isLoggedOut: boolean;
-  error?: unknown;
-};
-
-export type ActiveWebSendOptions = {
-  quotedMessageKey?: {
-    id: string;
-    remoteJid: string;
-    fromMe: boolean;
-    participant?: string;
-    messageText?: string;
-  };
-  gifPlayback?: boolean;
-  accountId?: string;
-  fileName?: string;
-};
-
-export type ActiveWebListener = {
-  sendMessage: (
-    to: string,
-    text: string,
-    mediaBuffer?: Buffer,
-    mediaType?: string,
-    options?: ActiveWebSendOptions,
-  ) => Promise<WhatsAppSendResult>;
-  sendPoll: (to: string, poll: PollInput) => Promise<WhatsAppSendResult>;
-  sendReaction: (
-    chatJid: string,
-    messageId: string,
-    emoji: string,
-    fromMe: boolean,
-    participant?: string,
-  ) => Promise<WhatsAppSendResult>;
-  sendComposingTo: (to: string) => Promise<void>;
-  close?: () => Promise<void>;
-};
-
-export type WhatsAppStructuredContactContext = {
-  kind: "contact" | "contacts";
-  total: number;
-  contacts: Array<{
-    name?: string;
-    phones?: string[];
-  }>;
-};
-
-export type WebInboundMessage = {
-  id?: string;
-  from: string; // conversation id: E.164 for direct chats, group JID for groups
-  conversationId: string; // alias for clarity (same as from)
-  to: string;
-  accountId: string;
-  /** Set by the real inbound monitor after access-control / pairing checks pass. */
-  accessControlPassed?: boolean;
-  body: string;
-  pushName?: string;
-  timestamp?: number;
-  chatType: "direct" | "group";
-  chatId: string;
-  sender?: WhatsAppIdentity;
-  senderJid?: string;
-  senderE164?: string;
-  senderName?: string;
-  replyTo?: WhatsAppReplyContext;
-  replyToId?: string;
-  replyToBody?: string;
-  replyToSender?: string;
-  replyToSenderJid?: string;
-  replyToSenderE164?: string;
-  groupSubject?: string;
-  groupParticipants?: string[];
-  mentions?: string[];
-  mentionedJids?: string[];
-  self?: WhatsAppSelfIdentity;
-  selfJid?: string | null;
-  selfLid?: string | null;
-  selfE164?: string | null;
-  fromMe?: boolean;
-  location?: NormalizedLocation;
-  sendComposing: () => Promise<void>;
-  reply: (text: string, options?: MiscMessageGenerationOptions) => Promise<WhatsAppSendResult>;
-  sendMedia: (
-    payload: AnyMessageContent,
-    options?: MiscMessageGenerationOptions,
-  ) => Promise<WhatsAppSendResult>;
-  mediaPath?: string;
-  mediaType?: string;
-  mediaFileName?: string;
-  mediaUrl?: string;
-  untrustedStructuredContext?: Array<{
-    label: string;
-    source?: string;
-    type?: string;
-    payload: unknown;
-  }>;
-  wasMentioned?: boolean;
-  isBatched?: boolean;
-};

package/src/inbound-context.contract.test.ts

@@ -1,32 +0,0 @@
-import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing";
-import { describe, it } from "vitest";
-
-describe("WhatsApp inbound context contract", () => {
-  it("keeps inbound context finalized", () => {
-    const ctx = {
-      Body: "Alice: hi",
-      BodyForAgent: "hi",
-      RawBody: "hi",
-      CommandBody: "hi",
-      BodyForCommands: "hi",
-      From: "123@g.us",
-      To: "+15550001111",
-      SessionKey: "agent:main:whatsapp:group:123",
-      AccountId: "default",
-      ChatType: "group",
-      ConversationLabel: "123@g.us",
-      GroupSubject: "Test Group",
-      SenderName: "Alice",
-      SenderId: "alice@s.whatsapp.net",
-      SenderE164: "+15550002222",
-      Provider: "whatsapp",
-      Surface: "whatsapp",
-      MessageSid: "msg1",
-      OriginatingChannel: "whatsapp",
-      OriginatingTo: "123@g.us",
-      CommandAuthorized: true,
-    };
-
-    expectChannelInboundContextContract(ctx);
-  });
-});