@openclaw/whatsapp 2026.5.1-beta.1

package/src/inbound/runtime-api.ts

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

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

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

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

@@ -0,0 +1,307 @@
+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("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

@@ -0,0 +1,141 @@
+import type {
+  AnyMessageContent,
+  MiscMessageGenerationOptions,
+  WAMessage,
+  WAPresence,
+} from "@whiskeysockets/baileys";
+import { recordChannelActivity } from "openclaw/plugin-sdk/channel-activity-runtime";
+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);
+      await params.sock.sendPresenceUpdate("composing", jid);
+    },
+  } as const;
+}

package/src/inbound/send-result.ts

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

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

@@ -0,0 +1,32 @@
+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);
+  });
+});