iMessage Setup Guide
Enables your agent to send and receive iMessages via a BlueBubbles server.
Prerequisites
- A Mac (macOS 11 Big Sur or later) that can stay powered on and connected to the internet
- An Apple ID signed in to iMessage on that Mac
- BlueBubbles server installed on the Mac
Step 1: Install BlueBubbles Server
BlueBubbles is an open-source app that bridges iMessage to a REST API.
- Download BlueBubbles Server from bluebubbles.app/install
- Install and open the app on your Mac
- Follow the setup wizard:
- Grant the required permissions (Full Disk Access, Accessibility, Notifications)
- Sign in with a Google account (used for Firebase Cloud Messaging)
- Set a server password — you'll need this for Carapace
Step 2: Get Your Server URL
Once the BlueBubbles server is running:
- Open the BlueBubbles Server app
- Go to the Connection tab
- Copy the Server URL (e.g.,
https://your-server-id.ngrok.ioor your custom domain)
The server URL may change if you're using ngrok without a reserved domain. For a stable connection, consider using a static ngrok domain or Cloudflare Tunnel.
Step 3: Connect in Carapace
- Go to Dashboard > Connections
- Find iMessage and click Connect
- Paste the Server URL from Step 2
- Enter the server password you set during BlueBubbles setup
- Click Save Credentials
Credential Fields Reference
| Field | Required | Format | Description |
|---|---|---|---|
server_url | Yes | URL (https) | BlueBubbles server URL |
password | Yes | String | BlueBubbles server password |
Gotchas
Mac must stay on: BlueBubbles requires an always-on Mac with iMessage active. If the Mac goes to sleep, shuts down, or loses internet, your agent won't be able to send or receive iMessages.
macOS only: BlueBubbles runs exclusively on macOS. There is no Windows or Linux version.
Server URL stability: If you're using ngrok's free tier, the URL changes each time the server restarts. Use a reserved ngrok domain or an alternative tunnel (Cloudflare Tunnel, Tailscale) for a stable URL.
iMessage activation: The Apple ID on the Mac must have iMessage enabled. Go to Messages > Settings > iMessage and ensure your account is signed in and active.
Private API: BlueBubbles offers a "Private API" mode that enables additional features (typing indicators, read receipts, better group chat support). This requires disabling SIP (System Integrity Protection) on the Mac. The standard mode works without SIP changes.