9c4eab69cc
* 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)
132 lines
3.0 KiB
Markdown
132 lines
3.0 KiB
Markdown
---
|
||
name: bluebubbles
|
||
description: Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".
|
||
metadata: { "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
|
||
|
||
```json
|
||
{
|
||
"action": "send",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"message": "hello from OpenClaw"
|
||
}
|
||
```
|
||
|
||
### React (tapback)
|
||
|
||
```json
|
||
{
|
||
"action": "react",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"messageId": "<message-guid>",
|
||
"emoji": "❤️"
|
||
}
|
||
```
|
||
|
||
### Remove a reaction
|
||
|
||
```json
|
||
{
|
||
"action": "react",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"messageId": "<message-guid>",
|
||
"emoji": "❤️",
|
||
"remove": true
|
||
}
|
||
```
|
||
|
||
### Edit a previously sent message
|
||
|
||
```json
|
||
{
|
||
"action": "edit",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"messageId": "<message-guid>",
|
||
"message": "updated text"
|
||
}
|
||
```
|
||
|
||
### Unsend a message
|
||
|
||
```json
|
||
{
|
||
"action": "unsend",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"messageId": "<message-guid>"
|
||
}
|
||
```
|
||
|
||
### Reply to a specific message
|
||
|
||
```json
|
||
{
|
||
"action": "reply",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"replyTo": "<message-guid>",
|
||
"message": "replying to that"
|
||
}
|
||
```
|
||
|
||
### Send an attachment
|
||
|
||
```json
|
||
{
|
||
"action": "sendAttachment",
|
||
"channel": "bluebubbles",
|
||
"target": "+15551234567",
|
||
"path": "/tmp/photo.jpg",
|
||
"caption": "here you go"
|
||
}
|
||
```
|
||
|
||
### Send with an iMessage effect
|
||
|
||
```json
|
||
{
|
||
"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.
|