OpenParable
Skip to content
← Back to skills

Bluebubbles

Apps & Automation
bluebubbles

Bluebubbles 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".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 (prefer chat_guid:...; also +15551234567 in E.164 or [email protected])
  • 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 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_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.