BlueBubbles plugin
Use this skill when working on the BlueBubbles channel plugin.
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 clawdbot/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=❤️