@openclaw/bluebubbles 2026.2.25 → 2026.3.2

package/README.md

@@ -10,7 +10,7 @@ If you’re looking for **how to use BlueBubbles as an agent/tool user**, see:
 
 - Extension package: `extensions/bluebubbles/` (entry: `index.ts`).
 - Channel implementation: `extensions/bluebubbles/src/channel.ts`.
-- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register via `api.registerHttpHandler`).
+- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register per-account route via `registerPluginHttpRoute`).
 - REST helpers: `extensions/bluebubbles/src/send.ts` + `extensions/bluebubbles/src/probe.ts`.
 - Runtime bridge: `extensions/bluebubbles/src/runtime.ts` (set via `api.runtime`).
 - Catalog entry for onboarding: `src/channels/plugins/catalog.ts`.

package/index.ts

@@ -1,7 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { bluebubblesPlugin } from "./src/channel.js";
-import { handleBlueBubblesWebhookRequest } from "./src/monitor.js";
 import { setBlueBubblesRuntime } from "./src/runtime.js";
 
 const plugin = {
@@ -12,7 +11,6 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setBlueBubblesRuntime(api.runtime);
     api.registerChannel({ plugin: bluebubblesPlugin });
-    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.25",
+  "version": "2026.3.2",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "openclaw": {

package/src/account-resolve.ts

@@ -1,5 +1,6 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import { resolveBlueBubblesAccount } from "./accounts.js";
+import { normalizeResolvedSecretInputString } from "./secret-input.js";
 
 export type BlueBubblesAccountResolveOpts = {
   serverUrl?: string;
@@ -18,8 +19,24 @@ export function resolveBlueBubblesServerAccount(params: BlueBubblesAccountResolv
     cfg: params.cfg ?? {},
     accountId: params.accountId,
   });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
+  const baseUrl =
+    normalizeResolvedSecretInputString({
+      value: params.serverUrl,
+      path: "channels.bluebubbles.serverUrl",
+    }) ||
+    normalizeResolvedSecretInputString({
+      value: account.config.serverUrl,
+      path: `channels.bluebubbles.accounts.${account.accountId}.serverUrl`,
+    });
+  const password =
+    normalizeResolvedSecretInputString({
+      value: params.password,
+      path: "channels.bluebubbles.password",
+    }) ||
+    normalizeResolvedSecretInputString({
+      value: account.config.password,
+      path: `channels.bluebubbles.accounts.${account.accountId}.password`,
+    });
   if (!baseUrl) {
     throw new Error("BlueBubbles serverUrl is required");
   }

package/src/accounts.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+
+describe("resolveBlueBubblesAccount", () => {
+  it("treats SecretRef passwords as configured when serverUrl exists", () => {
+    const resolved = resolveBlueBubblesAccount({
+      cfg: {
+        channels: {
+          bluebubbles: {
+            enabled: true,
+            serverUrl: "http://localhost:1234",
+            password: {
+              source: "env",
+              provider: "default",
+              id: "BLUEBUBBLES_PASSWORD",
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolved.configured).toBe(true);
+    expect(resolved.baseUrl).toBe("http://localhost:1234");
+  });
+});

package/src/accounts.ts

@@ -1,5 +1,10 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
+import { hasConfiguredSecretInput, normalizeSecretInputString } from "./secret-input.js";
 import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
 
 export type ResolvedBlueBubblesAccount = {
@@ -28,6 +33,13 @@ export function listBlueBubblesAccountIds(cfg: OpenClawConfig): string[] {
 }
 
 export function resolveDefaultBlueBubblesAccountId(cfg: OpenClawConfig): string {
+  const preferred = normalizeOptionalAccountId(cfg.channels?.bluebubbles?.defaultAccount);
+  if (
+    preferred &&
+    listBlueBubblesAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)
+  ) {
+    return preferred;
+  }
   const ids = listBlueBubblesAccountIds(cfg);
   if (ids.includes(DEFAULT_ACCOUNT_ID)) {
     return DEFAULT_ACCOUNT_ID;
@@ -52,8 +64,9 @@ function mergeBlueBubblesAccountConfig(
 ): BlueBubblesAccountConfig {
   const base = (cfg.channels?.bluebubbles ?? {}) as BlueBubblesAccountConfig & {
     accounts?: unknown;
+    defaultAccount?: unknown;
   };
-  const { accounts: _ignored, ...rest } = base;
+  const { accounts: _ignored, defaultAccount: _ignoredDefaultAccount, ...rest } = base;
   const account = resolveAccountConfig(cfg, accountId) ?? {};
   const chunkMode = account.chunkMode ?? rest.chunkMode ?? "length";
   return { ...rest, ...account, chunkMode };
@@ -67,9 +80,9 @@ export function resolveBlueBubblesAccount(params: {
   const baseEnabled = params.cfg.channels?.bluebubbles?.enabled;
   const merged = mergeBlueBubblesAccountConfig(params.cfg, accountId);
   const accountEnabled = merged.enabled !== false;
-  const serverUrl = merged.serverUrl?.trim();
-  const password = merged.password?.trim();
-  const configured = Boolean(serverUrl && password);
+  const serverUrl = normalizeSecretInputString(merged.serverUrl);
+  const password = normalizeSecretInputString(merged.password);
+  const configured = Boolean(serverUrl && hasConfiguredSecretInput(merged.password));
   const baseUrl = serverUrl ? normalizeBlueBubblesServerUrl(serverUrl) : undefined;
   return {
     accountId,

package/src/actions.ts

@@ -5,6 +5,7 @@ import {
   extractToolSend,
   jsonResult,
   readNumberParam,
+  readBooleanParam,
   readReactionParams,
   readStringParam,
   type ChannelMessageActionAdapter,
@@ -24,6 +25,7 @@ import {
 import { resolveBlueBubblesMessageId } from "./monitor.js";
 import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe.js";
 import { sendBlueBubblesReaction } from "./reactions.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
 import type { BlueBubblesSendTarget } from "./types.js";
@@ -52,23 +54,6 @@ function readMessageText(params: Record<string, unknown>): string | undefined {
   return readStringParam(params, "text") ?? readStringParam(params, "message");
 }
 
-function readBooleanParam(params: Record<string, unknown>, key: string): boolean | undefined {
-  const raw = params[key];
-  if (typeof raw === "boolean") {
-    return raw;
-  }
-  if (typeof raw === "string") {
-    const trimmed = raw.trim().toLowerCase();
-    if (trimmed === "true") {
-      return true;
-    }
-    if (trimmed === "false") {
-      return false;
-    }
-  }
-  return undefined;
-}
-
 /** Supported action names for BlueBubbles */
 const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);
 const PRIVATE_API_ACTIONS = new Set<ChannelMessageActionName>([
@@ -118,8 +103,8 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
       cfg: cfg,
       accountId: accountId ?? undefined,
     });
-    const baseUrl = account.config.serverUrl?.trim();
-    const password = account.config.password?.trim();
+    const baseUrl = normalizeSecretInputString(account.config.serverUrl);
+    const password = normalizeSecretInputString(account.config.password);
     const opts = { cfg: cfg, accountId: accountId ?? undefined };
     const assertPrivateApiEnabled = () => {
       if (getCachedBlueBubblesPrivateApiStatus(account.accountId) === false) {

package/src/attachments.test.ts

@@ -294,7 +294,7 @@ describe("downloadBlueBubblesAttachment", () => {
     expect(fetchMediaArgs.ssrfPolicy).toEqual({ allowPrivateNetwork: true });
   });
 
-  it("does not pass ssrfPolicy when allowPrivateNetwork is not set", async () => {
+  it("auto-allowlists serverUrl hostname when allowPrivateNetwork is not set", async () => {
     const mockBuffer = new Uint8Array([1]);
     mockFetch.mockResolvedValueOnce({
       ok: true,
@@ -309,7 +309,25 @@ describe("downloadBlueBubblesAttachment", () => {
     });
 
     const fetchMediaArgs = fetchRemoteMediaMock.mock.calls[0][0] as Record<string, unknown>;
-    expect(fetchMediaArgs.ssrfPolicy).toBeUndefined();
+    expect(fetchMediaArgs.ssrfPolicy).toEqual({ allowedHostnames: ["localhost"] });
+  });
+
+  it("auto-allowlists private IP serverUrl hostname when allowPrivateNetwork is not set", async () => {
+    const mockBuffer = new Uint8Array([1]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-private-ip" };
+    await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://192.168.1.5:1234",
+      password: "test",
+    });
+
+    const fetchMediaArgs = fetchRemoteMediaMock.mock.calls[0][0] as Record<string, unknown>;
+    expect(fetchMediaArgs.ssrfPolicy).toEqual({ allowedHostnames: ["192.168.1.5"] });
   });
 });
 

package/src/attachments.ts

@@ -62,6 +62,15 @@ function resolveAccount(params: BlueBubblesAttachmentOpts) {
   return resolveBlueBubblesServerAccount(params);
 }
 
+function safeExtractHostname(url: string): string | undefined {
+  try {
+    const hostname = new URL(url).hostname.trim();
+    return hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 type MediaFetchErrorCode = "max_bytes" | "http_error" | "fetch_failed";
 
 function readMediaFetchErrorCode(error: unknown): MediaFetchErrorCode | undefined {
@@ -89,12 +98,17 @@ export async function downloadBlueBubblesAttachment(
     password,
   });
   const maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : DEFAULT_ATTACHMENT_MAX_BYTES;
+  const trustedHostname = safeExtractHostname(baseUrl);
   try {
     const fetched = await getBlueBubblesRuntime().channel.media.fetchRemoteMedia({
       url,
       filePathHint: attachment.transferName ?? attachment.guid ?? "attachment",
       maxBytes,
-      ssrfPolicy: allowPrivateNetwork ? { allowPrivateNetwork: true } : undefined,
+      ssrfPolicy: allowPrivateNetwork
+        ? { allowPrivateNetwork: true }
+        : trustedHostname
+          ? { allowedHostnames: [trustedHostname] }
+          : undefined,
       fetchImpl: async (input, init) =>
         await blueBubblesFetchWithTimeout(
           resolveRequestUrl(input),

package/src/channel.ts

@@ -2,6 +2,7 @@ import type { ChannelAccountSnapshot, ChannelPlugin, OpenClawConfig } from "open
 import {
   applyAccountNameToChannelSection,
   buildChannelConfigSchema,
+  buildProbeChannelStatusSummary,
   collectBlueBubblesStatusIssues,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
@@ -356,16 +357,8 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
       lastError: null,
     },
     collectStatusIssues: collectBlueBubblesStatusIssues,
-    buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      baseUrl: snapshot.baseUrl ?? null,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
-      probe: snapshot.probe,
-      lastProbeAt: snapshot.lastProbeAt ?? null,
-    }),
+    buildChannelSummary: ({ snapshot }) =>
+      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
     probeAccount: async ({ account, timeoutMs }) =>
       probeBlueBubbles({
         baseUrl: account.baseUrl,

package/src/config-schema.test.ts

@@ -10,6 +10,18 @@ describe("BlueBubblesConfigSchema", () => {
     expect(parsed.success).toBe(true);
   });
 
+  it("accepts SecretRef password when serverUrl is set", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      serverUrl: "http://localhost:1234",
+      password: {
+        source: "env",
+        provider: "default",
+        id: "BLUEBUBBLES_PASSWORD",
+      },
+    });
+    expect(parsed.success).toBe(true);
+  });
+
   it("requires password when top-level serverUrl is configured", () => {
     const parsed = BlueBubblesConfigSchema.safeParse({
       serverUrl: "http://localhost:1234",

package/src/config-schema.ts

@@ -1,5 +1,6 @@
 import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
+import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
 
 const allowFromEntry = z.union([z.string(), z.number()]);
 
@@ -30,7 +31,7 @@ const bluebubblesAccountSchema = z
     enabled: z.boolean().optional(),
     markdown: MarkdownConfigSchema,
     serverUrl: z.string().optional(),
-    password: z.string().optional(),
+    password: buildSecretInputSchema().optional(),
     webhookPath: z.string().optional(),
     dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
     allowFrom: z.array(allowFromEntry).optional(),
@@ -49,8 +50,8 @@ const bluebubblesAccountSchema = z
   })
   .superRefine((value, ctx) => {
     const serverUrl = value.serverUrl?.trim() ?? "";
-    const password = value.password?.trim() ?? "";
-    if (serverUrl && !password) {
+    const passwordConfigured = hasConfiguredSecretInput(value.password);
+    if (serverUrl && !passwordConfigured) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         path: ["password"],
@@ -61,5 +62,6 @@ const bluebubblesAccountSchema = z
 
 export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
   accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),
+  defaultAccount: z.string().optional(),
   actions: bluebubblesActionSchema,
 });

package/src/monitor-debounce.ts

@@ -0,0 +1,205 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { NormalizedWebhookMessage } from "./monitor-normalize.js";
+import type { BlueBubblesCoreRuntime, WebhookTarget } from "./monitor-shared.js";
+
+/**
+ * Entry type for debouncing inbound messages.
+ * Captures the normalized message and its target for later combined processing.
+ */
+type BlueBubblesDebounceEntry = {
+  message: NormalizedWebhookMessage;
+  target: WebhookTarget;
+};
+
+export type BlueBubblesDebouncer = {
+  enqueue: (item: BlueBubblesDebounceEntry) => Promise<void>;
+  flushKey: (key: string) => Promise<void>;
+};
+
+export type BlueBubblesDebounceRegistry = {
+  getOrCreateDebouncer: (target: WebhookTarget) => BlueBubblesDebouncer;
+  removeDebouncer: (target: WebhookTarget) => void;
+};
+
+/**
+ * Default debounce window for inbound message coalescing (ms).
+ * This helps combine URL text + link preview balloon messages that BlueBubbles
+ * sends as separate webhook events when no explicit inbound debounce config exists.
+ */
+const DEFAULT_INBOUND_DEBOUNCE_MS = 500;
+
+/**
+ * Combines multiple debounced messages into a single message for processing.
+ * Used when multiple webhook events arrive within the debounce window.
+ */
+function combineDebounceEntries(entries: BlueBubblesDebounceEntry[]): NormalizedWebhookMessage {
+  if (entries.length === 0) {
+    throw new Error("Cannot combine empty entries");
+  }
+  if (entries.length === 1) {
+    return entries[0].message;
+  }
+
+  // Use the first message as the base (typically the text message)
+  const first = entries[0].message;
+
+  // Combine text from all entries, filtering out duplicates and empty strings
+  const seenTexts = new Set<string>();
+  const textParts: string[] = [];
+
+  for (const entry of entries) {
+    const text = entry.message.text.trim();
+    if (!text) {
+      continue;
+    }
+    // Skip duplicate text (URL might be in both text message and balloon)
+    const normalizedText = text.toLowerCase();
+    if (seenTexts.has(normalizedText)) {
+      continue;
+    }
+    seenTexts.add(normalizedText);
+    textParts.push(text);
+  }
+
+  // Merge attachments from all entries
+  const allAttachments = entries.flatMap((e) => e.message.attachments ?? []);
+
+  // Use the latest timestamp
+  const timestamps = entries
+    .map((e) => e.message.timestamp)
+    .filter((t): t is number => typeof t === "number");
+  const latestTimestamp = timestamps.length > 0 ? Math.max(...timestamps) : first.timestamp;
+
+  // Collect all message IDs for reference
+  const messageIds = entries
+    .map((e) => e.message.messageId)
+    .filter((id): id is string => Boolean(id));
+
+  // Prefer reply context from any entry that has it
+  const entryWithReply = entries.find((e) => e.message.replyToId);
+
+  return {
+    ...first,
+    text: textParts.join(" "),
+    attachments: allAttachments.length > 0 ? allAttachments : first.attachments,
+    timestamp: latestTimestamp,
+    // Use first message's ID as primary (for reply reference), but we've coalesced others
+    messageId: messageIds[0] ?? first.messageId,
+    // Preserve reply context if present
+    replyToId: entryWithReply?.message.replyToId ?? first.replyToId,
+    replyToBody: entryWithReply?.message.replyToBody ?? first.replyToBody,
+    replyToSender: entryWithReply?.message.replyToSender ?? first.replyToSender,
+    // Clear balloonBundleId since we've combined (the combined message is no longer just a balloon)
+    balloonBundleId: undefined,
+  };
+}
+
+function resolveBlueBubblesDebounceMs(
+  config: OpenClawConfig,
+  core: BlueBubblesCoreRuntime,
+): number {
+  const inbound = config.messages?.inbound;
+  const hasExplicitDebounce =
+    typeof inbound?.debounceMs === "number" || typeof inbound?.byChannel?.bluebubbles === "number";
+  if (!hasExplicitDebounce) {
+    return DEFAULT_INBOUND_DEBOUNCE_MS;
+  }
+  return core.channel.debounce.resolveInboundDebounceMs({ cfg: config, channel: "bluebubbles" });
+}
+
+export function createBlueBubblesDebounceRegistry(params: {
+  processMessage: (message: NormalizedWebhookMessage, target: WebhookTarget) => Promise<void>;
+}): BlueBubblesDebounceRegistry {
+  const targetDebouncers = new Map<WebhookTarget, BlueBubblesDebouncer>();
+
+  return {
+    getOrCreateDebouncer: (target) => {
+      const existing = targetDebouncers.get(target);
+      if (existing) {
+        return existing;
+      }
+
+      const { account, config, runtime, core } = target;
+      const debouncer = core.channel.debounce.createInboundDebouncer<BlueBubblesDebounceEntry>({
+        debounceMs: resolveBlueBubblesDebounceMs(config, core),
+        buildKey: (entry) => {
+          const msg = entry.message;
+          // Prefer stable, shared identifiers to coalesce rapid-fire webhook events for the
+          // same message (e.g., text-only then text+attachment).
+          //
+          // For balloons (URL previews, stickers, etc), BlueBubbles often uses a different
+          // messageId than the originating text. When present, key by associatedMessageGuid
+          // to keep text + balloon coalescing working.
+          const balloonBundleId = msg.balloonBundleId?.trim();
+          const associatedMessageGuid = msg.associatedMessageGuid?.trim();
+          if (balloonBundleId && associatedMessageGuid) {
+            return `bluebubbles:${account.accountId}:balloon:${associatedMessageGuid}`;
+          }
+
+          const messageId = msg.messageId?.trim();
+          if (messageId) {
+            return `bluebubbles:${account.accountId}:msg:${messageId}`;
+          }
+
+          const chatKey =
+            msg.chatGuid?.trim() ??
+            msg.chatIdentifier?.trim() ??
+            (msg.chatId ? String(msg.chatId) : "dm");
+          return `bluebubbles:${account.accountId}:${chatKey}:${msg.senderId}`;
+        },
+        shouldDebounce: (entry) => {
+          const msg = entry.message;
+          // Skip debouncing for from-me messages (they're just cached, not processed)
+          if (msg.fromMe) {
+            return false;
+          }
+          // Skip debouncing for control commands - process immediately
+          if (core.channel.text.hasControlCommand(msg.text, config)) {
+            return false;
+          }
+          // Debounce all other messages to coalesce rapid-fire webhook events
+          // (e.g., text+image arriving as separate webhooks for the same messageId)
+          return true;
+        },
+        onFlush: async (entries) => {
+          if (entries.length === 0) {
+            return;
+          }
+
+          // Use target from first entry (all entries have same target due to key structure)
+          const flushTarget = entries[0].target;
+
+          if (entries.length === 1) {
+            // Single message - process normally
+            await params.processMessage(entries[0].message, flushTarget);
+            return;
+          }
+
+          // Multiple messages - combine and process
+          const combined = combineDebounceEntries(entries);
+
+          if (core.logging.shouldLogVerbose()) {
+            const count = entries.length;
+            const preview = combined.text.slice(0, 50);
+            runtime.log?.(
+              `[bluebubbles] coalesced ${count} messages: "${preview}${combined.text.length > 50 ? "..." : ""}"`,
+            );
+          }
+
+          await params.processMessage(combined, flushTarget);
+        },
+        onError: (err) => {
+          runtime.error?.(
+            `[${account.accountId}] [bluebubbles] debounce flush failed: ${String(err)}`,
+          );
+        },
+      });
+
+      targetDebouncers.set(target, debouncer);
+      return debouncer;
+    },
+    removeDebouncer: (target) => {
+      targetDebouncers.delete(target);
+    },
+  };
+}