mirror of https://github.com/openclaw/openclaw.git synced 2026-02-19 18:39:20 -05:00

Files

Tyler Yust 9c4eab69cc iMessage: promote BlueBubbles and refresh docs/skills (#8415 )

* feat: Make BlueBubbles the primary iMessage integration

- Remove old imsg skill (skills/imsg/SKILL.md)
- Create new BlueBubbles skill (skills/bluebubbles/SKILL.md) with message tool examples
- Add keep-alive script documentation for VM/headless setups to docs/channels/bluebubbles.md
  - AppleScript that pokes Messages.app every 5 minutes
  - LaunchAgent configuration for automatic execution
  - Prevents Messages.app from going idle in VM environments
- Update all documentation to prioritize BlueBubbles over legacy imsg:
  - Mark imsg channel as legacy throughout docs
  - Update README.md channel lists
  - Update wizard, hubs, pairing, and index docs
  - Update FAQ to recommend BlueBubbles for iMessage
  - Update RPC docs to note imsg as legacy pattern
  - Update Chinese documentation (zh-CN)
- Replace imsg examples with generic macOS skill examples where appropriate

BlueBubbles is now the recommended first-class iMessage integration,
with the legacy imsg integration marked for potential future removal.

* refactor: Update import paths and improve code formatting

- Adjusted import paths in session-status-tool.ts, whatsapp-heartbeat.ts, and heartbeat-runner.ts for consistency.
- Reformatted code for better readability by aligning and grouping related imports and function parameters.
- Enhanced error messages and conditional checks for clarity in heartbeat-runner.ts.

* skills: restore imsg skill and align bluebubbles skill

* docs: update FAQ for clarity and formatting

- Adjusted the formatting of the FAQ section to ensure consistent bullet point alignment.
- No content changes were made, only formatting improvements for better readability.

* style: oxfmt touched files

* fix: preserve BlueBubbles developer reference (#8415) (thanks @tyler6204)

2026-02-03 18:06:54 -08:00

3.0 KiB

Raw Permalink Blame History

name, description, metadata

name

description

metadata

bluebubbles

Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".

openclaw

emoji

requires

🫧

config

channels.bluebubbles

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

3.0 KiB Raw Permalink Blame History Unescape Escape