@openclaw/bluebubbles 2026.2.2 → 2026.2.3

package/README.md

@@ -0,0 +1,45 @@
+# BlueBubbles extension (developer reference)
+
+This directory contains the **BlueBubbles external channel plugin** for OpenClaw.
+
+If you’re looking for **how to use BlueBubbles as an agent/tool user**, see:
+
+- `skills/bluebubbles/SKILL.md`
+
+## Layout
+
+- 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`).
+- 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`.
+
+## Internal helpers (use these, not raw API calls)
+
+- `probeBlueBubbles` in `extensions/bluebubbles/src/probe.ts` for health checks.
+- `sendMessageBlueBubbles` in `extensions/bluebubbles/src/send.ts` for text delivery.
+- `resolveChatGuidForTarget` in `extensions/bluebubbles/src/send.ts` for chat lookup.
+- `sendBlueBubblesReaction` in `extensions/bluebubbles/src/reactions.ts` for tapbacks.
+- `sendBlueBubblesTyping` + `markBlueBubblesChatRead` in `extensions/bluebubbles/src/chat.ts`.
+- `downloadBlueBubblesAttachment` in `extensions/bluebubbles/src/attachments.ts` for inbound media.
+- `buildBlueBubblesApiUrl` + `blueBubblesFetchWithTimeout` in `extensions/bluebubbles/src/types.ts` for shared REST plumbing.
+
+## Webhooks
+
+- BlueBubbles posts JSON to the gateway HTTP server.
+- Normalize sender/chat IDs defensively (payloads vary by version).
+- Skip messages marked as from self.
+- Route into core reply pipeline via the plugin runtime (`api.runtime`) and `openclaw/plugin-sdk` helpers.
+- For attachments/stickers, use `<media:...>` placeholders when text is empty and attach media paths via `MediaUrl(s)` in the inbound context.
+
+## Config (core)
+
+- `channels.bluebubbles.serverUrl` (base URL), `channels.bluebubbles.password`, `channels.bluebubbles.webhookPath`.
+- Action gating: `channels.bluebubbles.actions.reactions` (default true).
+
+## Message tool notes
+
+- **Reactions:** the `react` action requires a `target` (phone number or chat identifier) in addition to `messageId`.
+  Example:
+  `action=react target=+15551234567 messageId=ABC123 emoji=❤️`

package/package.json

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

package/src/monitor.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import {
+  createReplyPrefixOptions,
   logAckFailure,
   logInboundDrop,
   logTypingFailure,
@@ -2173,10 +2174,17 @@ async function processMessage(
     }, typingRestartDelayMs);
   };
   try {
+    const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+      cfg: config,
+      agentId: route.agentId,
+      channel: "bluebubbles",
+      accountId: account.accountId,
+    });
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
       ctx: ctxPayload,
       cfg: config,
       dispatcherOptions: {
+        ...prefixOptions,
         deliver: async (payload, info) => {
           const rawReplyToId =
             typeof payload.replyToId === "string" ? payload.replyToId.trim() : "";
@@ -2288,6 +2296,7 @@ async function processMessage(
         },
       },
       replyOptions: {
+        onModelSelected,
         disableBlockStreaming:
           typeof account.config.blockStreaming === "boolean"
             ? !account.config.blockStreaming