BlueBubbles Actions
Overview
BlueBubbles is OpenClaw’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 OpenClaw"
}
React (tapback)
{
"action"
:
"react"
,
"channel"
:
"bluebubbles"
,
"target"
:
"+15551234567"
,
"messageId"
:
""
,
"emoji"
:
"❤️"
}
Remove a reaction
{
"action"
:
"react"
,
"channel"
:
"bluebubbles"
,
"target"
:
"+15551234567"
,
"messageId"
:
""
,
"emoji"
:
"❤️"
,
"remove"
:
true
}
Edit a previously sent message
{
"action"
:
"edit"
,
"channel"
:
"bluebubbles"
,
"target"
:
"+15551234567"
,
"messageId"
:
""
,
"message"
:
"updated text"
}
Unsend a message
{
"action"
:
"unsend"
,
"channel"
:
"bluebubbles"
,
"target"
:
"+15551234567"
,
"messageId"
:
""
}
Reply to a specific message
{
"action"
:
"reply"
,
"channel"
:
"bluebubbles"
,
"target"
:
"+15551234567"
,
"replyTo"
:
""
,
"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.