A comprehensive development toolkit for building, updating, and managing BlueBubbles messaging channel integrations within the Clawdbot framework.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install bluebubbles
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install bluebubbles using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is BlueBubbles Plugin Skill?
The BlueBubbles skill is a dedicated development resource designed for engineers working with the BlueBubbles external channel plugin. It provides a structured approach to managing extension packages, implementing REST-based communication, and handling complex webhook logic. By utilizing this Openclaw Skills entry, developers can ensure their agents maintain robust connectivity with iMessage via the BlueBubbles bridge, facilitating seamless message delivery and reception.
This skill streamlines the implementation of the runtime bridge and ensures that all internal helpers, such as health probes and chat lookup utilities, are correctly integrated into the core platform. It focuses on maintaining a clean separation between the gateway HTTP server and the internal plugin logic, ensuring reliable performance in production environments.
BlueBubbles Plugin Skill Use Cases
- Developing custom chat integrations between BlueBubbles and automated AI agents.
- Implementing real-time webhook listeners to sync iMessage conversations with external databases.
- Automating tapback reactions and typing indicators within an Openclaw Skills workflow.
- Handling complex media attachments and stickers by normalizing inbound JSON payloads from BlueBubbles servers.
How BlueBubbles Plugin Skill Works
- The skill initializes the extension package within the extensions/bluebubbles/ directory, setting index.ts as the entry point.
- It establishes a runtime bridge using api.runtime to connect the plugin to the main application core.
- The system registers a webhook handler via the monitor module to capture inbound JSON posts from the BlueBubbles server.
- Incoming messages are defensively normalized to handle various version-specific payload structures while filtering out self-sent messages.
- Outbound communication is handled through optimized REST helpers that manage message delivery, chat GUID resolution, and tapback reactions.
BlueBubbles Plugin Skill Setup
To get started with this plugin using Openclaw Skills, you must configure your server credentials and file paths. First, navigate to the extension directory:
cd extensions/bluebubbles/
npm install
Then, add the following configuration to your settings file to enable the BlueBubbles channel:
channels:
bluebubbles:
serverUrl: "https://your-bluebubbles-instance.com"
password: "your_secure_password"
webhookPath: "/your-unique-webhook-id"
actions:
reactions: true
BlueBubbles Plugin Skill Data Schema & Taxonomy
The BlueBubbles skill follows a modular data architecture to ensure maintainability. The following table describes the primary file organization:
| File Path | Responsibility | Key Components |
|---|---|---|
src/channel.ts |
Channel Interface | Main plugin implementation and gateway integration |
src/monitor.ts |
Webhook Logic | Inbound HTTP handling and message normalization |
src/send.ts |
Outbound REST | Message delivery and chat GUID resolution |
src/attachments.ts |
Media Handling | Attachment downloading and local storage mapping |
src/types.ts |
Shared Plumbing | API URL building and fetch utilities with timeouts |
BlueBubbles Plugin Skill Advanced Features
- Advanced Tapback Support: Utilize the react action which requires both a messageId and a specific target phone number or chat identifier.
- Intelligent Media Mapping: Automatically converts empty text messages with attachments into media:... placeholders for consistent processing within Openclaw Skills.
- Automated Chat Maintenance: Built-in support for marking chats as read and sending typing indicators to mimic human behavior.
- Catalog Integration: Integrated onboarding support via the global channel catalog for easier plugin activation.
SKILL.md
Loading
Related Openclaw Skills
Workflow Migrate
A specialized migration tool that transforms fragile SaaS automations into production-grade, self-hosted scripts with built-in error handling.
Spec-First Development
A spec-driven development workflow that enforces architectural planning and user approval before any code is written.
Morning Coffee Briefing
A daily briefing agent that synthesizes your tasks and memory files into a prioritized action plan delivered via Telegram to eliminate decision fatigue.
Freelance Proposal Writer
Automate the creation of high-converting, problem-first freelance proposals to maximize your win rate and save connects on major platforms.
Gettr Transcribe & Summarize (MLX Whisper)
A local AI workflow for converting GETTR video content into searchable transcripts and structured Markdown summaries.
Gettr Transcribe (MLX Whisper)
A high-performance local transcription tool for GETTR content optimized for Apple Silicon using MLX Whisper.
Featured*
