Skip to main content

BlueBubbles (iMessage)

Connect Hermes to Apple iMessage via BlueBubbles — a free, open-source macOS server that bridges iMessage to any device.

Prerequisites​

  • A Mac (always on) running BlueBubbles Server
  • 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. 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:

hermes gateway setup

Select BlueBubbles (iMessage) and enter your server URL and password.

Or set environment variables directly in ~/.hermes/.env:

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

4. Authorize Users​

Choose one approach:

DM Pairing (recommended): When someone messages your iMessage, Hermes automatically sends them a pairing code. Approve it with:

hermes pairing approve bluebubbles <CODE>

Use hermes pairing list to see pending codes and approved users.

Pre-authorize specific users (in ~/.hermes/.env):

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

Open access (in ~/.hermes/.env):

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Start the Gateway​

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​

VariableRequiredDefaultDescription
BLUEBUBBLES_SERVER_URLYes—BlueBubbles server URL
BLUEBUBBLES_PASSWORDYes—Server password
BLUEBUBBLES_WEBHOOK_HOSTNo127.0.0.1Webhook listener bind address
BLUEBUBBLES_WEBHOOK_PORTNo8645Webhook listener port
BLUEBUBBLES_WEBHOOK_PATHNo/bluebubbles-webhookWebhook URL path
BLUEBUBBLES_HOME_CHANNELNo—Phone/email for cron delivery
BLUEBUBBLES_ALLOWED_USERSNo—Comma-separated authorized users
BLUEBUBBLES_ALLOW_ALL_USERSNofalseAllow all users
BLUEBUBBLES_SEND_READ_RECEIPTSNotrueAuto-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.

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:

  • 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 logs gateway for webhook errors (or hermes logs -f to follow in real-time)

"Private API helper not connected"​

  • Install the Private API helper: docs.bluebubbles.app
  • Basic messaging works without it — only reactions, typing, and read receipts require it