From 7120d6cdd6a6e3d0559185caabaef203dceca622 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Thu, 9 Apr 2026 00:19:05 -0700 Subject: [PATCH] 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.) --- gateway/session.py | 1 + hermes_cli/skills_config.py | 1 + website/docs/developer-guide/architecture.md | 4 +- .../docs/developer-guide/cron-internals.md | 1 + .../docs/developer-guide/gateway-internals.md | 1 + website/docs/index.md | 2 +- website/docs/integrations/index.md | 4 +- .../docs/reference/environment-variables.md | 7 + website/docs/reference/toolsets-reference.md | 1 + website/docs/user-guide/configuration.md | 2 +- website/docs/user-guide/features/cron.md | 1 + .../docs/user-guide/messaging/bluebubbles.md | 141 ++++++++++++++++++ website/docs/user-guide/messaging/index.md | 6 +- website/docs/user-guide/sessions.md | 1 + website/sidebars.ts | 1 + 15 files changed, 167 insertions(+), 7 deletions(-) create mode 100644 website/docs/user-guide/messaging/bluebubbles.md diff --git a/gateway/session.py b/gateway/session.py index 64f04ad9c9..72c3eb1618 100644 --- 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>`` diff --git a/hermes_cli/skills_config.py b/hermes_cli/skills_config.py index 7b44014ea5..d7e47ca5f2 100644 --- 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", diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md index c08161b32f..38fbfb138c 100644 --- 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) diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.md index cc8435dbee..2f14d4e1a5 100644 --- 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::` (e.g., `telegram:-1001234567890:17585`). diff --git a/website/docs/developer-guide/gateway-internals.md b/website/docs/developer-guide/gateway-internals.md index 1371bdd340..cf25cecd9a 100644 --- 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 diff --git a/website/docs/index.md b/website/docs/index.md index f4b5378f4c..0f180673ac 100644 --- 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 diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md index ce103f1cc8..e6fe54f776 100644 --- 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. diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 00b428697f..e8f2e8aee6 100644 --- 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 | diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md index 1c225b233d..ba04d5c777 100644 --- 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. | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 4431e06828..0ac24db184 100644 --- 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 diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index ff63848d8a..b463d5a7be 100644 --- 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. diff --git a/website/docs/user-guide/messaging/bluebubbles.md b/website/docs/user-guide/messaging/bluebubbles.md new file mode 100644 index 0000000000..3f023d3179 --- /dev/null +++ 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 diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md index fa662305be..4e7d3514f9 100644 --- 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
(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) diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md index a84e1064db..358574030a 100644 --- 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 | diff --git a/website/sidebars.ts b/website/sidebars.ts index 5e1ebf2d6b..39b60d88e9 100644 --- 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', ],