OpenClaw · Skill
Bluebubbles
Use this skill when working on the BlueBubbles channel plugin.
Clawdbot Tools
v1.0.0
VirusTotal: Benign
Install
Start with the primary install command. Alternate entrypoints are included below for ClawHub and OpenClaw CLI users.
Primary command
clawhub install kevin19830331/bluebubblesClawHub installer
npx clawhub@latest install kevin19830331/bluebubblesOpenClaw CLI
openclaw skills install kevin19830331/bluebubblesDirect OpenClaw install
openclaw install kevin19830331/bluebubblesWhat this skill does
Use this skill when working on the BlueBubbles channel plugin.
Why it matters
Lets Clawdbot participate in iMessage threads without native Apple infrastructure by delegating to a user-controlled BlueBubbles server.
Typical use cases
- Routing iMessage conversations into a Clawdbot reply pipeline
- Sending automated text replies to iMessages via a Mac-hosted BlueBubbles server
- Forwarding inbound iMessage attachments and stickers to the bot for processing
- Sending tapback reactions to specific iMessages by phone number and message ID
- Health-checking a BlueBubbles server before enabling the channel
Source instructions
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 viaapi.registerHttpHandler). - REST helpers:
extensions/bluebubbles/src/send.ts+extensions/bluebubbles/src/probe.ts. - Runtime bridge:
extensions/bluebubbles/src/runtime.ts(set viaapi.runtime). - Catalog entry for onboarding:
src/channels/plugins/catalog.ts.
Internal helpers (use these, not raw API calls)
probeBlueBubblesinextensions/bluebubbles/src/probe.tsfor health checks.sendMessageBlueBubblesinextensions/bluebubbles/src/send.tsfor text delivery.resolveChatGuidForTargetinextensions/bluebubbles/src/send.tsfor chat lookup.sendBlueBubblesReactioninextensions/bluebubbles/src/reactions.tsfor tapbacks.sendBlueBubblesTyping+markBlueBubblesChatReadinextensions/bluebubbles/src/chat.ts.downloadBlueBubblesAttachmentinextensions/bluebubbles/src/attachments.tsfor inbound media.buildBlueBubblesApiUrl+blueBubblesFetchWithTimeoutinextensions/bluebubbles/src/types.tsfor 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) andclawdbot/plugin-sdkhelpers. - For attachments/stickers, use
<media:...>placeholders when text is empty and attach media paths viaMediaUrl(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
reactaction requires atarget(phone number or chat identifier) in addition tomessageId. Example:action=react target=+15551234567 messageId=ABC123 emoji=❤️