Bluebubbles

BlueBubbles Actions

Overview

BlueBubbles is Brigade’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

jsonCopy code
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "hello from Brigade"
}

React (tapback)

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

Remove a reaction

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

Edit a previously sent message

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

Unsend a message

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

Reply to a specific message

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

Send an attachment

jsonCopy code
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "path": "/tmp/photo.jpg",
  "message": "here you go"
}

Use message for the user-facing text. Do not rely on caption as a distinct BlueBubbles/iMessage feature.

Send with an iMessage effect

jsonCopy code
{
  "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).
• For media + text, treat message as canonical. Brigade can accept caption as an alias, but BlueBubbles/iMessage does not offer a reliable native attachment-caption concept.
• In practice, media with text may arrive as the attachment plus a separate text message rather than one captioned bubble. Do not promise exact attachment-caption rendering.
• If you must use the channel-specific file action, the canonical action name is upload-file; sendAttachment is a legacy alias.
• 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 the BlueBubbles plugin package README.

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 short message text, expecting BlueBubbles to treat the text as best-effort companion text rather than a guaranteed native caption.