fix(bluebubbles): add missing integration points and documentation (#6460)

- hermes_cli/skills_config.py: add platform label for per-platform skill config - gateway/session.py: add to PII-safe platforms (no mention system) - website/docs/user-guide/messaging/bluebubbles.md: full setup guide - website/sidebars.ts: sidebar navigation entry - 10 docs pages: add BlueBubbles to all platform enumerations (env vars, toolsets, cron delivery, gateway internals, etc.)
2026-04-25 00:51:20 +00:00 · 2026-04-09 00:19:05 -07:00 · 2026-04-09 00:19:05 -07:00 · 7120d6cdd6
commit 7120d6cdd6
parent d40264d53b
15 changed files with 167 additions and 7 deletions
--- a/gateway/session.py
+++ b/gateway/session.py
@ -193,6 +193,7 @@ _PII_SAFE_PLATFORMS = frozenset({
    Platform.WHATSAPP,
    Platform.SIGNAL,
    Platform.TELEGRAM,
+    Platform.BLUEBUBBLES,
 })
 """Platforms where user IDs can be safely redacted (no in-message mention system
 that requires raw IDs).  Discord is excluded because mentions use ``<@user_id>``
--- a/hermes_cli/skills_config.py
+++ b/hermes_cli/skills_config.py
@ -23,6 +23,7 @@ PLATFORMS = {
    "slack":    "💼 Slack",
    "whatsapp": "📱 WhatsApp",
    "signal":   "📡 Signal",
+    "bluebubbles": "💬 BlueBubbles",
    "email":    "📧 Email",
    "homeassistant": "🏠 Home Assistant",
    "mattermost": "💬 Mattermost",
--- a/website/docs/developer-guide/architecture.md
+++ b/website/docs/developer-guide/architecture.md
@ -116,9 +116,9 @@ hermes-agent/
 │   ├── mirror.py             # Cross-session message mirroring
 │   ├── status.py             # Token locks, profile-scoped process tracking
 │   ├── builtin_hooks/        # Always-registered hooks
-│   └── platforms/            # 14 adapters: telegram, discord, slack, whatsapp,
+│   └── platforms/            # 15 adapters: telegram, discord, slack, whatsapp,
 │                             #   signal, matrix, mattermost, email, sms,
-│                             #   dingtalk, feishu, wecom, homeassistant, webhook
+│                             #   dingtalk, feishu, wecom, bluebubbles, homeassistant, webhook
 │
 ├── acp_adapter/              # ACP server (VS Code / Zed / JetBrains)
 ├── cron/                     # Scheduler (jobs.py, scheduler.py)
--- a/website/docs/developer-guide/cron-internals.md
+++ b/website/docs/developer-guide/cron-internals.md
@ -153,6 +153,7 @@ Cron job results can be delivered to any supported platform:
 | DingTalk | `dingtalk` | Deliver to DingTalk |
 | Feishu | `feishu` | Deliver to Feishu |
 | WeCom | `wecom` | Deliver to WeCom |
+| BlueBubbles | `bluebubbles` | Deliver to iMessage via BlueBubbles |

 For Telegram topics, use the format `telegram:<chat_id>:<thread_id>` (e.g., `telegram:-1001234567890:17585`).

--- a/website/docs/developer-guide/gateway-internals.md
+++ b/website/docs/developer-guide/gateway-internals.md
@ -160,6 +160,7 @@ gateway/platforms/
 ├── dingtalk.py          # DingTalk WebSocket
 ├── feishu.py            # Feishu/Lark WebSocket or webhook
 ├── wecom.py             # WeCom (WeChat Work) callback
+├── bluebubbles.py       # Apple iMessage via BlueBubbles macOS server
 ├── webhook.py           # Inbound/outbound webhook adapter
 ├── api_server.py        # REST API server adapter
 └── homeassistant.py     # Home Assistant conversation integration
--- a/website/docs/index.md
+++ b/website/docs/index.md
@ -46,7 +46,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl

 - **A closed learning loop** — Agent-curated memory with periodic nudges, autonomous skill creation, skill self-improvement during use, FTS5 cross-session recall with LLM summarization, and [Honcho](https://github.com/plastic-labs/honcho) dialectic user modeling
 - **Runs anywhere, not just your laptop** — 6 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal. Daytona and Modal offer serverless persistence — your environment hibernates when idle, costing nearly nothing
- **Lives where you do** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, Home Assistant — 14+ platforms from one gateway
+- **Lives where you do** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, BlueBubbles, Home Assistant — 15+ platforms from one gateway
 - **Built by model trainers** — Created by [Nous Research](https://nousresearch.com), the lab behind Hermes, Nomos, and Psyche. Works with [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai), OpenAI, or any endpoint
 - **Scheduled automations** — Built-in cron with delivery to any platform
 - **Delegates & parallelizes** — Spawn isolated subagents for parallel workstreams. Programmatic Tool Calling via `execute_code` collapses multi-step pipelines into single inference calls
--- a/website/docs/integrations/index.md
+++ b/website/docs/integrations/index.md
@ -80,9 +80,9 @@ Speech-to-text supports three providers: local Whisper (free, runs on-device), G

 ## Messaging Platforms

-Hermes runs as a gateway bot on 14+ messaging platforms, all configured through the same `gateway` subsystem:
+Hermes runs as a gateway bot on 15+ messaging platforms, all configured through the same `gateway` subsystem:

- **[Telegram](/docs/user-guide/messaging/telegram)**, **[Discord](/docs/user-guide/messaging/discord)**, **[Slack](/docs/user-guide/messaging/slack)**, **[WhatsApp](/docs/user-guide/messaging/whatsapp)**, **[Signal](/docs/user-guide/messaging/signal)**, **[Matrix](/docs/user-guide/messaging/matrix)**, **[Mattermost](/docs/user-guide/messaging/mattermost)**, **[Email](/docs/user-guide/messaging/email)**, **[SMS](/docs/user-guide/messaging/sms)**, **[DingTalk](/docs/user-guide/messaging/dingtalk)**, **[Feishu/Lark](/docs/user-guide/messaging/feishu)**, **[WeCom](/docs/user-guide/messaging/wecom)**, **[Home Assistant](/docs/user-guide/messaging/homeassistant)**, **[Webhooks](/docs/user-guide/messaging/webhooks)**
+- **[Telegram](/docs/user-guide/messaging/telegram)**, **[Discord](/docs/user-guide/messaging/discord)**, **[Slack](/docs/user-guide/messaging/slack)**, **[WhatsApp](/docs/user-guide/messaging/whatsapp)**, **[Signal](/docs/user-guide/messaging/signal)**, **[Matrix](/docs/user-guide/messaging/matrix)**, **[Mattermost](/docs/user-guide/messaging/mattermost)**, **[Email](/docs/user-guide/messaging/email)**, **[SMS](/docs/user-guide/messaging/sms)**, **[DingTalk](/docs/user-guide/messaging/dingtalk)**, **[Feishu/Lark](/docs/user-guide/messaging/feishu)**, **[WeCom](/docs/user-guide/messaging/wecom)**, **[BlueBubbles](/docs/user-guide/messaging/bluebubbles)**, **[Home Assistant](/docs/user-guide/messaging/homeassistant)**, **[Webhooks](/docs/user-guide/messaging/webhooks)**

 See the [Messaging Gateway overview](/docs/user-guide/messaging) for the platform comparison table and setup guide.

--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@ -228,6 +228,13 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
 | `WECOM_WEBSOCKET_URL` | Custom WebSocket URL (default: `wss://openws.work.weixin.qq.com`) |
 | `WECOM_ALLOWED_USERS` | Comma-separated WeCom user IDs allowed to message the bot |
 | `WECOM_HOME_CHANNEL` | WeCom chat ID for cron delivery and notifications |
+| `BLUEBUBBLES_SERVER_URL` | BlueBubbles server URL (e.g. `http://192.168.1.10:1234`) |
+| `BLUEBUBBLES_PASSWORD` | BlueBubbles server password |
+| `BLUEBUBBLES_WEBHOOK_HOST` | Webhook listener bind address (default: `127.0.0.1`) |
+| `BLUEBUBBLES_WEBHOOK_PORT` | Webhook listener port (default: `8645`) |
+| `BLUEBUBBLES_HOME_CHANNEL` | Phone/email for cron/notification delivery |
+| `BLUEBUBBLES_ALLOWED_USERS` | Comma-separated authorized users |
+| `BLUEBUBBLES_ALLOW_ALL_USERS` | Allow all users (`true`/`false`) |
 | `MATTERMOST_URL` | Mattermost server URL (e.g. `https://mm.example.com`) |
 | `MATTERMOST_TOKEN` | Bot token or personal access token for Mattermost |
 | `MATTERMOST_ALLOWED_USERS` | Comma-separated Mattermost user IDs allowed to message the bot |
--- a/website/docs/reference/toolsets-reference.md
+++ b/website/docs/reference/toolsets-reference.md
@ -103,6 +103,7 @@ Platform toolsets define the complete tool configuration for a deployment target
 | `hermes-dingtalk` | Same as `hermes-cli`. |
 | `hermes-feishu` | Same as `hermes-cli`. |
 | `hermes-wecom` | Same as `hermes-cli`. |
+| `hermes-bluebubbles` | Same as `hermes-cli`. |
 | `hermes-homeassistant` | Same as `hermes-cli`. |
 | `hermes-webhook` | Same as `hermes-cli`. |
 | `hermes-gateway` | Union of all messaging platform toolsets. Used internally when the gateway needs the broadest possible tool set. |
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@ -843,7 +843,7 @@ display:
    slack: 'off'              # quiet in shared Slack workspace
 ```

-Platforms without an override fall back to the global `tool_progress` value. Valid platform keys: `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `matrix`, `mattermost`, `email`, `sms`, `homeassistant`, `dingtalk`, `feishu`, `wecom`.
+Platforms without an override fall back to the global `tool_progress` value. Valid platform keys: `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `matrix`, `mattermost`, `email`, `sms`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `bluebubbles`.

 ## Privacy

--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@ -202,6 +202,7 @@ When scheduling jobs, you specify where the output goes:
 | `"dingtalk"` | DingTalk | |
 | `"feishu"` | Feishu/Lark | |
 | `"wecom"` | WeCom | |
+| `"bluebubbles"` | BlueBubbles (iMessage) | |

 The agent's final response is automatically delivered. You do not need to call `send_message` in the cron prompt.

--- a/website/docs/user-guide/messaging/bluebubbles.md
+++ b/website/docs/user-guide/messaging/bluebubbles.md
@ -0,0 +1,141 @@
+# BlueBubbles (iMessage)
+
+Connect Hermes to Apple iMessage via [BlueBubbles](https://bluebubbles.app/) — a free, open-source macOS server that bridges iMessage to any device.
+
+## Prerequisites
+
+- A **Mac** (always on) running [BlueBubbles Server](https://bluebubbles.app/)
+- Apple ID signed into Messages.app on that Mac
+- BlueBubbles Server v1.0.0+ (webhooks require this version)
+- Network connectivity between Hermes and the BlueBubbles server
+
+## Setup
+
+### 1. Install BlueBubbles Server
+
+Download and install from [bluebubbles.app](https://bluebubbles.app/). Complete the setup wizard — sign in with your Apple ID and configure a connection method (local network, Ngrok, Cloudflare, or Dynamic DNS).
+
+### 2. Get your Server URL and Password
+
+In BlueBubbles Server → **Settings → API**, note:
+- **Server URL** (e.g., `http://192.168.1.10:1234`)
+- **Server Password**
+
+### 3. Configure Hermes
+
+Run the setup wizard:
+
+```bash
+hermes gateway setup
+```
+
+Select **BlueBubbles (iMessage)** and enter your server URL and password.
+
+Or set environment variables directly in `~/.hermes/.env`:
+
+```bash
+BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
+BLUEBUBBLES_PASSWORD=your-server-password
+```
+
+### 4. Authorize Users
+
+Choose one approach:
+
+**DM Pairing (recommended):**
+```bash
+hermes pairing generate bluebubbles
+```
+Share the pairing code — the user sends it via iMessage to get approved.
+
+**Pre-authorize specific users:**
+```bash
+BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567
+```
+
+**Open access:**
+```bash
+BLUEBUBBLES_ALLOW_ALL_USERS=true
+```
+
+### 5. Start the Gateway
+
+```bash
+hermes gateway run
+```
+
+Hermes will connect to your BlueBubbles server, register a webhook, and start listening for iMessage messages.
+
+## How It Works
+
+```
+iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
+Hermes → BlueBubbles REST API → Messages.app → iMessage
+```
+
+- **Inbound:** BlueBubbles sends webhook events to a local listener when new messages arrive. No polling — instant delivery.
+- **Outbound:** Hermes sends messages via the BlueBubbles REST API.
+- **Media:** Images, voice messages, videos, and documents are supported in both directions. Inbound attachments are downloaded and cached locally for the agent to process.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BLUEBUBBLES_SERVER_URL` | Yes | — | BlueBubbles server URL |
+| `BLUEBUBBLES_PASSWORD` | Yes | — | Server password |
+| `BLUEBUBBLES_WEBHOOK_HOST` | No | `127.0.0.1` | Webhook listener bind address |
+| `BLUEBUBBLES_WEBHOOK_PORT` | No | `8645` | Webhook listener port |
+| `BLUEBUBBLES_WEBHOOK_PATH` | No | `/bluebubbles-webhook` | Webhook URL path |
+| `BLUEBUBBLES_HOME_CHANNEL` | No | — | Phone/email for cron delivery |
+| `BLUEBUBBLES_ALLOWED_USERS` | No | — | Comma-separated authorized users |
+| `BLUEBUBBLES_ALLOW_ALL_USERS` | No | `false` | Allow all users |
+| `BLUEBUBBLES_SEND_READ_RECEIPTS` | No | `true` | Auto-mark messages as read |
+
+## Features
+
+### Text Messaging
+Send and receive iMessages. Markdown is automatically stripped for clean plain-text delivery.
+
+### Rich Media
+- **Images:** Photos appear natively in the iMessage conversation
+- **Voice messages:** Audio files sent as iMessage voice messages
+- **Videos:** Video attachments
+- **Documents:** Files sent as iMessage attachments
+
+### Tapback Reactions
+Love, like, dislike, laugh, emphasize, and question reactions. Requires the BlueBubbles [Private API helper](https://docs.bluebubbles.app/helper-bundle/installation).
+
+### Typing Indicators
+Shows "typing..." in the iMessage conversation while the agent is processing. Requires Private API.
+
+### Read Receipts
+Automatically marks messages as read after processing. Requires Private API.
+
+### Chat Addressing
+You can address chats by email or phone number — Hermes resolves them to BlueBubbles chat GUIDs automatically. No need to use raw GUID format.
+
+## Private API
+
+Some features require the BlueBubbles [Private API helper](https://docs.bluebubbles.app/helper-bundle/installation):
+- Tapback reactions
+- Typing indicators
+- Read receipts
+- Creating new chats by address
+
+Without the Private API, basic text messaging and media still work.
+
+## Troubleshooting
+
+### "Cannot reach server"
+- Verify the server URL is correct and the Mac is on
+- Check that BlueBubbles Server is running
+- Ensure network connectivity (firewall, port forwarding)
+
+### Messages not arriving
+- Check that the webhook is registered in BlueBubbles Server → Settings → API → Webhooks
+- Verify the webhook URL is reachable from the Mac
+- Check `hermes gateway logs` for webhook errors
+
+### "Private API helper not connected"
+- Install the Private API helper: [docs.bluebubbles.app](https://docs.bluebubbles.app/helper-bundle/installation)
+- Basic messaging works without it — only reactions, typing, and read receipts require it
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@ -6,7 +6,7 @@ description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal,

 # Messaging Gateway

-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, BlueBubbles (iMessage), or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

 For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/docs/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-hermes).

@ -27,6 +27,7 @@ For the full voice feature set — including CLI microphone mode, spoken replies
 | DingTalk | — | — | — | — | — | ✅ | ✅ |
 | Feishu/Lark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | WeCom | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
+| BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — |

 **Voice** = TTS audio replies and/or voice message transcription. **Images** = send/receive images. **Files** = send/receive file attachments. **Threads** = threaded conversations. **Reactions** = emoji reactions on messages. **Typing** = typing indicator while processing. **Streaming** = progressive message updates via editing.

@ -49,6 +50,7 @@ flowchart TB
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
+    bb[BlueBubbles]
            api["API Server<br/>(OpenAI-compatible)"]
            wh[Webhooks]
        end
@ -352,6 +354,7 @@ Each platform has its own toolset:
 | DingTalk | `hermes-dingtalk` | Full tools including terminal |
 | Feishu/Lark | `hermes-feishu` | Full tools including terminal |
 | WeCom | `hermes-wecom` | Full tools including terminal |
+| BlueBubbles | `hermes-bluebubbles` | Full tools including terminal |
 | API Server | `hermes` (default) | Full tools including terminal |
 | Webhooks | `hermes-webhook` | Full tools including terminal |

@ -370,5 +373,6 @@ Each platform has its own toolset:
 - [DingTalk Setup](dingtalk.md)
 - [Feishu/Lark Setup](feishu.md)
 - [WeCom Setup](wecom.md)
+- [BlueBubbles Setup (iMessage)](bluebubbles.md)
 - [Open WebUI + API Server](open-webui.md)
 - [Webhooks](webhooks.md)
--- a/website/docs/user-guide/sessions.md
+++ b/website/docs/user-guide/sessions.md
@ -44,6 +44,7 @@ Each session is tagged with its source platform:
 | `dingtalk` | DingTalk messenger |
 | `feishu` | Feishu/Lark messenger |
 | `wecom` | WeCom (WeChat Work) |
+| `bluebubbles` | Apple iMessage via BlueBubbles macOS server |
 | `homeassistant` | Home Assistant conversation |
 | `webhook` | Incoming webhooks |
 | `api-server` | API server requests |
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@ -107,6 +107,7 @@ const sidebars: SidebarsConfig = {
        'user-guide/messaging/dingtalk',
        'user-guide/messaging/feishu',
        'user-guide/messaging/wecom',
+        'user-guide/messaging/bluebubbles',
        'user-guide/messaging/open-webui',
        'user-guide/messaging/webhooks',
      ],