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)
This commit is contained in:
Tyler Yust
@@ -1,44 +1,131 @@
|
||||
---
|
||||
name: bluebubbles
|
||||
description: Build or update the BlueBubbles external channel plugin for OpenClaw (extension package, REST send/probe, webhook inbound).
|
||||
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 plugin
|
||||
# BlueBubbles Actions
|
||||
|
||||
Use this skill when working on the BlueBubbles channel plugin.
|
||||
## Overview
|
||||
|
||||
## Layout
|
||||
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.
|
||||
|
||||
- Extension package: `extensions/bluebubbles/` (entry: `index.ts`).
|
||||
- Channel implementation: `extensions/bluebubbles/src/channel.ts`.
|
||||
- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register via `api.registerHttpHandler`).
|
||||
- REST helpers: `extensions/bluebubbles/src/send.ts` + `extensions/bluebubbles/src/probe.ts`.
|
||||
- Runtime bridge: `extensions/bluebubbles/src/runtime.ts` (set via `api.runtime`).
|
||||
- Catalog entry for onboarding: `src/channels/plugins/catalog.ts`.
|
||||
## Inputs to collect
|
||||
|
||||
## Internal helpers (use these, not raw API calls)
|
||||
- `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
|
||||
|
||||
- `probeBlueBubbles` in `extensions/bluebubbles/src/probe.ts` for health checks.
|
||||
- `sendMessageBlueBubbles` in `extensions/bluebubbles/src/send.ts` for text delivery.
|
||||
- `resolveChatGuidForTarget` in `extensions/bluebubbles/src/send.ts` for chat lookup.
|
||||
- `sendBlueBubblesReaction` in `extensions/bluebubbles/src/reactions.ts` for tapbacks.
|
||||
- `sendBlueBubblesTyping` + `markBlueBubblesChatRead` in `extensions/bluebubbles/src/chat.ts`.
|
||||
- `downloadBlueBubblesAttachment` in `extensions/bluebubbles/src/attachments.ts` for inbound media.
|
||||
- `buildBlueBubblesApiUrl` + `blueBubblesFetchWithTimeout` in `extensions/bluebubbles/src/types.ts` for shared REST plumbing.
|
||||
If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content.
|
||||
|
||||
## Webhooks
|
||||
## Actions
|
||||
|
||||
- BlueBubbles posts JSON to the gateway HTTP server.
|
||||
- Normalize sender/chat IDs defensively (payloads vary by version).
|
||||
- Skip messages marked as from self.
|
||||
- Route into core reply pipeline via the plugin runtime (`api.runtime`) and `openclaw/plugin-sdk` helpers.
|
||||
- For attachments/stickers, use `<media:...>` placeholders when text is empty and attach media paths via `MediaUrl(s)` in the inbound context.
|
||||
### Send a message
|
||||
|
||||
## Config (core)
|
||||
```json
|
||||
{
|
||||
"action": "send",
|
||||
"channel": "bluebubbles",
|
||||
"target": "+15551234567",
|
||||
"message": "hello from OpenClaw"
|
||||
}
|
||||
```
|
||||
|
||||
- `channels.bluebubbles.serverUrl` (base URL), `channels.bluebubbles.password`, `channels.bluebubbles.webhookPath`.
|
||||
- Action gating: `channels.bluebubbles.actions.reactions` (default true).
|
||||
### React (tapback)
|
||||
|
||||
## Message tool notes
|
||||
```json
|
||||
{
|
||||
"action": "react",
|
||||
"channel": "bluebubbles",
|
||||
"target": "+15551234567",
|
||||
"messageId": "<message-guid>",
|
||||
"emoji": "❤️"
|
||||
}
|
||||
```
|
||||
|
||||
- **Reactions:** The `react` action requires a `target` (phone number or chat identifier) in addition to `messageId`. Example: `action=react target=+15551234567 messageId=ABC123 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.
|
||||
|
||||
@@ -23,24 +23,52 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# imsg
|
||||
# imsg Actions
|
||||
|
||||
## Overview
|
||||
|
||||
Use `imsg` to read and send Messages.app iMessage/SMS on macOS.
|
||||
|
||||
Requirements
|
||||
Requirements: Messages.app signed in, Full Disk Access for your terminal, and Automation permission to control Messages.app for sending.
|
||||
|
||||
- Messages.app signed in
|
||||
- Full Disk Access for your terminal
|
||||
- Automation permission to control Messages.app (for sending)
|
||||
## Inputs to collect
|
||||
|
||||
Common commands
|
||||
- Recipient handle (phone/email) for `send`
|
||||
- `chatId` for history/watch (from `imsg chats --limit 10 --json`)
|
||||
- `text` and optional `file` path for sends
|
||||
|
||||
- List chats: `imsg chats --limit 10 --json`
|
||||
- History: `imsg history --chat-id 1 --limit 20 --attachments --json`
|
||||
- Watch: `imsg watch --chat-id 1 --attachments`
|
||||
- Send: `imsg send --to "+14155551212" --text "hi" --file /path/pic.jpg`
|
||||
## Actions
|
||||
|
||||
Notes
|
||||
### List chats
|
||||
|
||||
```bash
|
||||
imsg chats --limit 10 --json
|
||||
```
|
||||
|
||||
### Fetch chat history
|
||||
|
||||
```bash
|
||||
imsg history --chat-id 1 --limit 20 --attachments --json
|
||||
```
|
||||
|
||||
### Watch a chat
|
||||
|
||||
```bash
|
||||
imsg watch --chat-id 1 --attachments
|
||||
```
|
||||
|
||||
### Send a message
|
||||
|
||||
```bash
|
||||
imsg send --to "+14155551212" --text "hi" --file /path/pic.jpg
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- `--service imessage|sms|auto` controls delivery.
|
||||
- Confirm recipient + message before sending.
|
||||
|
||||
## Ideas to try
|
||||
|
||||
- Use `imsg chats --limit 10 --json` to discover chat ids.
|
||||
- Watch a high-signal chat to stream incoming messages.
|
||||
|
||||
Reference in New Issue
Block a user