bluebubbles

Files (1)

• SKILL.md

SKILL.md (first lines)

# BlueBubbles Actions

## Overview

BlueBubbles is SolanaOS'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.

## Daemon Integration

BlueBubbles is a first-class channel in the SolanaOS Go daemon (`pkg/channels/bluebubbles/`). Configure via env vars:

```bash
BLUEBUBBLES_SERVER_URL=http://localhost:1234   # Your BlueBubbles server
BLUEBUBBLES_PASSWORD=your-server-password
BLUEBUBBLES_WEBHOOK_PATH=/webhooks/bb          # Optional webhook endpoint
BLUEBUBBLES_ALLOW_FROM=+17324063563            # Optional sender allowlist
```

Or in your config JSON:

```json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "server_url": "http://localhost:1234",
      "password": "your-server-password",
      "webhook_path": "/webhooks/bb",
      "allow_from": ["+17324063563"]
    }
  }
}
```

The daemon polls for new inbound iMessages every 5 seconds and routes them through the same OODA agent loop as Telegram and X messages.

## Clawd Code Channels Automation

BlueBubbles can also be used as a Clawd Code channel plugin for push-event automation. With channels enabled, iMessages arrive directly in your running Clawd Code session:

```bash
# Install the iMessage channel plugin
/plugin install imessage@clawd-plugins-official

# Restart with channels enabled
clawd --channels plugin:imessage@clawd-plugins-official

# Or combine with Telegram
clawd --channels plugin:telegram@clawd-plugins-official plugin:imessage@clawd-plugins-official
```

This lets you:
- Push iMessages into a running session so Clawd can react while you're away
- Use Clawd as a two-way iMessage bridge — it reads the event and replies back through BlueBubbles
- Forward alerts, CI results, and monitoring events via iMessage

## Actions

### Send a message

```json
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+17324063563",
  "message": "hello from SolanaOS"
}
```

### React (tapback)

```json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+17324063563",
  "messageId": "<message-guid>",
  "emoji": "❤️"
}
```

### Remove a reaction

```json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+17324063563",
  "messageId": "<message-guid>",
  "emoji": "❤️",
  "remove": true
}
```

### Edit a previously sent message

```json
{
  "action": "edit",
  "channel": "bluebubbles",
  "target": "+17324063563",
  "messageId": "<message-guid>",
  "message": "updated text"
}
```

### Unsend a message

```json
{
  "action": "unsend",

From x402agent/openclawd-ts, MIT.

More from x402agent/openclawd-ts