Bluebubbles
Apps & AutomationbluebubblesBluebubbles is an Agent Skill for apps & automation published in the Bitterbot-AI/bitterbot-desktop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Bitterbot-AI/bitterbot-desktop/blob/HEAD/skills/bluebubbles/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bluebubbles, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
BlueBubbles Actions
Overview
BlueBubbles is Bitterbot’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(preferchat_guid:...; also+15551234567in E.164 or[email protected])messagetext for send/edit/replymessageIdfor react/edit/unsend/reply- Attachment
pathfor local files, orbuffer+filenamefor 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 Bitterbot"
}
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_guidtargets 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.