How do I install the Bluebubbles skill?

Run npx skillmds add majiayu000/bluebubbles in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Bluebubbles safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Bluebubbles?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Bluebubbles free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Bluebubbles?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Bluebubbles by majiayu000 — Agent Skill

Name: Bluebubbles
Rating: 4.5 (4 reviews)
Author: majiayu000

File contents

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 espada/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=❤️

---name: bluebubblesdescription: Build or update the BlueBubbles external channel plugin for Espada (extension package, REST send/probe, webhook inbound).--- # 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 `espada/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=❤️`

Frequently asked questions