BlueBubbles Hermes — AI Agent on iMessage

BlueBubbles — AI on iMessage

Ever wished you could run an AI assistant right inside your iPhone’s Messages app? Not a separate app, not a bot you have to switch to — your actual iMessage thread, where your friends and family already are. That’s exactly what BlueBubbles + Hermes gives you.

BlueBubbles is a free, open-source macOS server that bridges iMessage to other devices and apps. When you connect it to Hermes, your AI agent can read incoming iMessages, reply to them, send photos, react with tapbacks, and even show typing indicators — all from your own phone number or Apple ID.

Let’s walk through the setup.

What You’ll Need

• A Mac that stays on (it runs the BlueBubbles server)
• Your Apple ID signed into Messages.app on that Mac
• BlueBubbles Server v1.0.0 or newer (webhooks require this version)
• Network access between Hermes and your Mac

Step 1: Install BlueBubbles Server

Head to bluebubbles.app, download the server, and run the setup wizard. You’ll sign in with your Apple ID and pick a connection method — local network, Ngrok, Cloudflare, or Dynamic DNS all work fine.

Step 2: Grab Your Server URL and Password

Open BlueBubbles Server → Settings → API. You’ll see two things you need:

• Server URL (looks like http://192.168.1.10:1234)
• Server Password

Keep these handy.

Step 3: Configure Hermes

The easiest way is to run the setup wizard:

hermes gateway setup

Pick BlueBubbles (iMessage) and paste in your server URL and password.

Prefer editing files? Add these to ~/.hermes/.env:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

Step 4: Authorize Users

By default, Hermes will pair with anyone who messages you. When someone texts your iMessage, Hermes sends them a pairing code. Approve it with:

hermes pairing approve bluebubbles <CODE>

You can see pending codes with hermes pairing list.

Want to skip pairing? Pre-authorize specific users in .env:

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

Or open it up to everyone (not recommended unless you trust your inbox):

BLUEBUBBLES_ALLOW_ALL_USERS=true

Step 5: Start the Gateway

hermes gateway run

Hermes connects to your BlueBubbles server, registers a webhook, and starts listening. No polling — messages arrive instantly.

How It Works

Here’s the flow:

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage

Inbound messages come through webhooks (instant). Outbound messages go through the REST API. Media works both ways — images, voice messages, videos, and documents are downloaded and cached locally for the agent to process.

Two URLs, Opposite Directions

The setup uses two URLs that point in opposite directions — don’t mix them up:

• BLUEBUBBLES_SERVER_URL (e.g. http://192.168.1.10:1234) — Hermes calls your BlueBubbles server’s API. This is the Server URL shown in BlueBubbles Server → Settings → API.
• The webhook (default http://localhost:8645/bluebubbles-webhook) — BlueBubbles POSTs new-message events to Hermes. Its host/port/path come from BLUEBUBBLES_WEBHOOK_HOST / BLUEBUBBLES_WEBHOOK_PORT / BLUEBUBBLES_WEBHOOK_PATH.

How the Webhook Is Registered

You do not need to create a webhook in the BlueBubbles UI. When the gateway connects, Hermes registers the webhook itself via the BlueBubbles REST API (/api/v1/webhook) for the new-message and updated-message events, and removes the registration again on clean shutdown. Two details worth knowing:

• The registered URL carries the server password as a query parameter (?password=…) because the BlueBubbles webhook API does not support custom headers — that is how inbound events are authenticated.
• The webhook listener binds to 127.0.0.1 by default. Fine when Hermes and BlueBubbles run on the same machine; if they are on different machines, set BLUEBUBBLES_WEBHOOK_HOST to an address the Mac running BlueBubbles can reach.

Verify the Setup

The setup wizard saves your credentials to ~/.hermes/.env — it does not write platforms.bluebubbles.enabled into ~/.hermes/config.yaml. With no explicit setting, present credentials are enough for the adapter to start; but an explicit enabled: false always wins over credentials, so if you previously disabled the adapter (for example while using another iMessage bridge) the wizard reports success and the adapter still never starts. Check the stored setting:

hermes config get platforms.bluebubbles.enabled

• true — explicitly enabled
• Config key not set — no explicit setting; the .env credentials drive enablement
• false — explicitly disabled; re-running setup will not flip this, so set it to true yourself

Then look for the two log lines that prove the connection and the webhook registration:

hermes logs gateway

[bluebubbles] connected to http://192.168.1.10:1234 (private_api=False, helper=False)
[bluebubbles] webhook registered with server: http://localhost:8645/bluebubbles-webhook?password=***

Finally, send yourself a test message from another device — a reply (or the pairing code for a new DM) is the end-to-end proof that inbound delivery works.

New in This Version: Group Chat Mentions

Previously, Hermes responded to every message in a group chat. Now you can require a mention first. Enable it in ~/.hermes/config.yaml:

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

With this on, DMs still work normally, but group messages are ignored unless they mention Hermes. Default patterns cover “Hermes” and “@Hermes agent” variants. For a custom name, set your own regex:

platforms:
  bluebubbles:
    extra:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

Nice Extras (Require Private API)

Install the Private API helper to unlock:

• Tapback reactions — love, like, laugh, emphasize, and more
• Typing indicators — shows “typing…” while the agent works
• Read receipts — auto-marks messages as read
• Creating new chats by address — no raw GUIDs needed

Without the Private API, basic text and media still work fine. One caveat: “basic messaging works without Private API” assumes BlueBubbles can drive Messages.app in the foreground of a logged-in macOS user. If the Mac running BlueBubbles stays at the login screen, or the server user is switched away from (Fast User Switching), AppleScript-based sending fails — see BlueBubbles: multiple users on the same Mac. In that setup the Private API is required for reliable sending, not just for the extras above.

Troubleshooting

“Cannot reach server” — Check the server URL and make sure the Mac is on. Note that Hermes uses BLUEBUBBLES_SERVER_URL from ~/.hermes/.env, not the Server URL shown in the BlueBubbles UI (which can be stale after a DHCP change).

Messages not arriving — Check hermes logs gateway for webhook errors. Hermes registers the webhook itself on connect, so only inspect BlueBubbles Server → Settings → API → Webhooks if the log shows a registration failure. A webhook row in the BlueBubbles UI is not proof of delivery — the end-to-end proof is Hermes logging the message and replying. If Hermes and BlueBubbles run on different machines, the default webhook bind address 127.0.0.1 is unreachable from the Mac: set BLUEBUBBLES_WEBHOOK_HOST to a reachable address and restart the gateway.

Setup succeeded, but the adapter never starts — An explicit enabled: false in ~/.hermes/config.yaml wins over credentials being present. Check with hermes config get platforms.bluebubbles.enabled. This commonly bites after switching iMessage bridges: re-running setup will not re-enable the adapter, so set enabled: true (and disable the bridge you no longer use — two iMessage bridges will double-handle messages).

Two BlueBubbles servers on one Mac (wrong Apple ID) — Two macOS users on one Mac each run their own BlueBubbles server with its own API port and Apple ID. Verify which one Hermes reaches with curl "http://<server-url>/api/v1/server/info?password=<password>" and compare the computer_id. For the multi-user setup itself, follow BlueBubbles: multiple users on the same Mac — one port per user, and don’t log out the user running the server.

Duplicate replies — Known issue: session handling can split one correspondent into two sessions (raw-GUID form vs. phone/email form), tracked in #30708 and #34372. This is not a documentation or configuration problem — follow those issues for fixes.

“♻️ Recovered reply” repeats, or sends hang for minutes — If a BLUEBUBBLES_HOME_CHANNEL is configured, gateway restarts and platform reconnects notify the home channel and may re-deliver pending replies as “♻️ Recovered reply”. If sends on the BlueBubbles side silently fail — typically AppleScript errors like Not authorized to send Apple events to Messages. (-1743) with long timeouts on a background macOS user — the retries pile up and can crowd out webhook delivery. Leave the home channel empty until sending is proven reliable through the Private API helper.

Wrap-Up

BlueBubbles turns your iMessage into an AI playground. With Hermes connected, you get instant replies, rich media, reactions, and typing indicators — all from your real phone number. The new mention gating keeps group chats clean, and the pairing system keeps things secure.

Ready to give your iMessage a brain? Set up BlueBubbles and let Hermes handle the rest.