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.

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.

Troubleshooting

“Cannot reach server” — Check the URL, make sure the Mac is on, and verify network connectivity (firewall, port forwarding).

Messages not arriving — Confirm the webhook is registered in BlueBubbles Server → Settings → API → Webhooks. Check hermes logs gateway for errors.

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.