mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-26 01:01:40 +00:00
b650957b40
The docs incorrectly referenced 'hermes pairing generate bluebubbles' which doesn't exist. The existing reactive pairing flow already handles this — when an unknown user messages the bot, it sends them a code automatically, and the owner approves with 'hermes pairing approve'.
142 lines
5 KiB
Markdown
142 lines
5 KiB
Markdown
# 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):**
|
|
When someone messages your iMessage, Hermes automatically sends them a pairing code. Approve it with:
|
|
```bash
|
|
hermes pairing approve bluebubbles <CODE>
|
|
```
|
|
Use `hermes pairing list` to see pending codes and approved users.
|
|
|
|
**Pre-authorize specific users** (in `~/.hermes/.env`):
|
|
```bash
|
|
BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567
|
|
```
|
|
|
|
**Open access** (in `~/.hermes/.env`):
|
|
```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
|