How do I install the Bluebubbles skill?

Run npx skillmds@latest add elizaos/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?

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

Bluebubbles by elizaos — Agent Skill

Name: Bluebubbles
Rating: 4.2 (5 reviews)
Author: elizaOS

Bluebubbles

Handles sending and managing iMessages through BlueBubbles, the recommended iMessage integration. Triggers when the user wants to send a text message, send an iMessage, send a text, text someone, message a contact, react with a tapback, reply to a message thread, send an attachment via iMessage, edit or unsend a sent message, or manage group chat participants. All calls go through the generic message tool with channel="bluebubbles".

elizaOS Updated Sep 9, 2026

File contents

BlueBubbles Actions

Overview

BlueBubbles is Otto’s recommended iMessage integration. Use the message tool with channel: "bluebubbles" to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons.

Inputs to collect

target (prefer chat_guid:...; also +15551234567 in E.164 or user@example.com)
message text for send/edit/reply
messageId for react/edit/unsend/reply
Attachment path for local files, or buffer + filename for base64

If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content.

Actions

Send a message

{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "hello from Otto"
}

React (tapback)

{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️"
}

Remove a reaction

{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️",
  "remove": true
}

Edit a previously sent message

{
  "action": "edit",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "message": "updated text"
}

Unsend a message

{
  "action": "unsend",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>"
}

Reply to a specific message

{
  "action": "reply",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "replyTo": "<message-guid>",
  "message": "replying to that"
}

Send an attachment

{
  "action": "sendAttachment",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "path": "/tmp/photo.jpg",
  "caption": "here you go"
}

Send with an iMessage effect

{
  "action": "sendWithEffect",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "big news",
  "effect": "balloons"
}

Notes

Requires gateway config channels.bluebubbles (serverUrl/password/webhookPath).
Prefer chat_guid targets when you have them (especially for group chats).
BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe).
The gateway may expose both short and full message ids; full ids are more durable across restarts.
Developer reference for the underlying plugin lives in extensions/bluebubbles/README.md.

Ideas to try

React with a tapback to acknowledge a request.
Reply in-thread when a user references a specific message.
Send a file attachment with a short caption.

---name: bluebubblesdescription: Handles sending and managing iMessages through BlueBubbles, the recommended iMessage integration. Triggers when the user wants to send a text message, send an iMessage, send a text, text someone, message a contact, react with a tapback, reply to a message thread, send an attachment via iMessage, edit or unsend a sent message, or manage group chat participants. All calls go through the generic message tool with channel="bluebubbles".--- # BlueBubbles Actions ## Overview BlueBubbles is Otto’s recommended iMessage integration. Use the `message` tool with `channel: "bluebubbles"` to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons. ## Inputs to collect - `target` (prefer `chat_guid:...`; also `+15551234567` in E.164 or `user@example.com`) - `message` text for send/edit/reply - `messageId` for react/edit/unsend/reply - Attachment `path` for local files, or `buffer` + `filename` for base64 If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content. ## Actions ### Send a message ```json { "action": "send", "channel": "bluebubbles", "target": "+15551234567", "message": "hello from Otto" } ``` ### React (tapback) ```json { "action": "react", "channel": "bluebubbles", "target": "+15551234567", "messageId": "<message-guid>", "emoji": "❤️" } ``` ### Remove a reaction ```json { "action": "react", "channel": "bluebubbles", "target": "+15551234567", "messageId": "<message-guid>", "emoji": "❤️", "remove": true } ``` ### Edit a previously sent message ```json { "action": "edit", "channel": "bluebubbles", "target": "+15551234567", "messageId": "<message-guid>", "message": "updated text" } ``` ### Unsend a message ```json { "action": "unsend", "channel": "bluebubbles", "target": "+15551234567", "messageId": "<message-guid>" } ``` ### Reply to a specific message ```json { "action": "reply", "channel": "bluebubbles", "target": "+15551234567", "replyTo": "<message-guid>", "message": "replying to that" } ``` ### Send an attachment ```json { "action": "sendAttachment", "channel": "bluebubbles", "target": "+15551234567", "path": "/tmp/photo.jpg", "caption": "here you go" } ``` ### Send with an iMessage effect ```json { "action": "sendWithEffect", "channel": "bluebubbles", "target": "+15551234567", "message": "big news", "effect": "balloons" } ``` ## Notes - Requires gateway config `channels.bluebubbles` (serverUrl/password/webhookPath). - Prefer `chat_guid` targets when you have them (especially for group chats). - BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe). - The gateway may expose both short and full message ids; full ids are more durable across restarts. - Developer reference for the underlying plugin lives in `extensions/bluebubbles/README.md`. ## Ideas to try - React with a tapback to acknowledge a request. - Reply in-thread when a user references a specific message. - Send a file attachment with a short caption.

Frequently asked questions