Bluebubbles

Build or update the BlueBubbles external channel plugin for Clawdbot (extension package, REST send/probe, webhook inbound).

Security Scan

The skill is an instruction-only developer guide for building a BlueBubbles channel plugin and its requirements and references are consistent with that purpose.

Purpose & Capability

The name/description (BlueBubbles channel plugin) matches the files, helpers, and runtime hooks the SKILL.md references. Required credentials/config are declared as core config keys (serverUrl/password/webhookPath), not unrelated services, so requested capabilities are proportional to the stated purpose.

Instruction Scope

SKILL.md only describes repository paths, helper functions, webhook behavior, and how to route messages into the core runtime. It does not instruct access to unrelated system files, credentials outside the plugin config, or external endpoints beyond the BlueBubbles gateway integration.

Install Mechanism

No install spec or code files are present (instruction-only). Nothing is downloaded or written to disk by the skill itself.

Credentials

The skill references core config keys (channels.bluebubbles.serverUrl, channels.bluebubbles.password, channels.bluebubbles.webhookPath) which are reasonable for a messaging plugin. The skill itself does not declare required env vars or credentials, but deployment will require those config values—ensure they are supplied securely by the host application.

Persistence & Privilege

The skill is not always-on and has default invocation settings. As an instruction-only skill it does not request persistent system presence or modify other skills' configs.

Assessment

This is a developer-facing instruction file for implementing a BlueBubbles channel plugin and appears coherent with that goal. There is no code bundled here, so the immediate security risk is low. Before installing or enabling a plugin implementation based on these instructions, confirm where the BlueBubbles server URL and password will be stored (use your application's secure config/secret storage), review any actual code added to the repo for network calls or credential handling, and only provide webhook endpoints and credentials to trusted code. If you want extra assurance, ask for the actual plugin code (not just the SKILL.md) and review it for unexpected network calls or filesystem access.

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=[phone] messageId=ABC123 emoji=❤️