BlueBubbles Setup (iMessage)

BlueBubbles is a free, open-source iMessage bridge that runs on any Mac with iMessage signed in. Users message your assistant’s iCloud email address from the Messages app on any Apple device.

Prerequisites

• A Mac that stays on (Mac Mini, old MacBook, etc.)
• An Apple ID signed into iMessage on that Mac
• A way to expose the BlueBubbles server to the internet (ngrok, Cloudflare Tunnel, or port forwarding)

1. Set up the Mac

Create a dedicated Apple ID

Create a new Apple ID (e.g. clawbolt-demo@icloud.com) for the assistant. This keeps your personal iMessage separate and gives users a clean address to text.

Sign into iMessage

1. Open Messages on the Mac
2. Sign in with the dedicated Apple ID
3. In Messages > Settings > iMessage, confirm the account is active

Prevent sleep

The Mac must stay awake for BlueBubbles to work:

1. Open System Settings > Energy Saver (or Battery on laptops)
2. Set “Turn display off after” to Never (or use a short time but enable “Prevent automatic sleeping when the display is off”)
3. Disable Put hard disks to sleep when possible

2. Install BlueBubbles Server

1. Download the latest .dmg from BlueBubbles releases
2. Drag to Applications and open it
3. Grant Full Disk Access in System Settings > Privacy & Security > Full Disk Access (required to read the iMessage database)
4. Grant Accessibility permissions if prompted

3. Configure BlueBubbles Server

1. Set a server password. You will use this as BLUEBUBBLES_PASSWORD in Clawbolt.
2. Under Connection, choose a proxy service:
   • Ngrok (easiest): paste your ngrok auth token. BlueBubbles will provide a URL like https://abc123.ngrok.io.
   • Cloudflare Tunnel: if you have a domain and Cloudflare account.
   • Dynamic DNS + port forwarding: if you control your router.
3. Start the server. Note the server URL displayed in BlueBubbles.

Ngrok considerations

The free ngrok tier generates a new URL on every restart. Options:

• Ngrok paid plan ($8/month): get a stable subdomain
• Cloudflare Tunnel (free): stable URL with your own domain
• Re-register webhook: update BLUEBUBBLES_SERVER_URL after each restart

4. Configure Clawbolt

Add these to your .env file:

BLUEBUBBLES_SERVER_URL=https://your-mac-url.ngrok.io
BLUEBUBBLES_PASSWORD=your-server-password

Access control

BlueBubbles rejects all inbound messages by default. Configure which senders are allowed:

# Allow a specific phone number (E.164 format) or iCloud email
BLUEBUBBLES_ALLOWED_NUMBERS=+15559876543

# Allow everyone (useful for development)
BLUEBUBBLES_ALLOWED_NUMBERS=*

5. Register the webhook

If Clawbolt runs behind a Cloudflare Tunnel, it auto-registers the webhook on startup. Otherwise, register manually in BlueBubbles:

1. Open BlueBubbles Server settings
2. Go to the Webhooks tab
3. Add a new webhook:
   • URL: https://your-clawbolt-url/api/webhooks/bluebubbles?password=your-server-password
   • Events: new-message

6. Start texting

Tell users to open Messages on their iPhone, iPad, or Mac and start a new conversation to your assistant’s iCloud email (e.g. clawbolt-demo@icloud.com). Clawbolt will respond via iMessage.

Important: This only works between Apple devices. BlueBubbles is iMessage-only without a paired iPhone. There is no SMS/green bubble support unless you also connect an iPhone to the same Apple ID with SMS forwarding enabled.

How it works

• Inbound messages arrive via webhook at /api/webhooks/bluebubbles with password query param validation
• Outbound messages are sent via the BlueBubbles REST API (/api/v1/message/text and /api/v1/message/attachment)
• Media (photos, documents) is supported in both directions
• Typing indicators are sent while the agent is processing

Security

• Inbound webhooks are validated with the server password (query parameter)
• Sender allowlist prevents unauthorized access
• Idempotency tracking prevents duplicate message processing
• The BlueBubbles server password is used for all API authentication

Troubleshooting

Bot does not respond to iMessages

• Check Clawbolt server logs for allowlist rejections
• Verify BLUEBUBBLES_SERVER_URL and BLUEBUBBLES_PASSWORD are set correctly
• Confirm the BlueBubbles server is running and the proxy URL is reachable
• Make sure the sender is using iMessage (blue bubble), not SMS (green bubble)

Webhook not registering on startup

• Auto-registration requires a Cloudflare Tunnel. For ngrok, register the webhook manually in BlueBubbles.
• Check Clawbolt logs for BlueBubbles-related errors

Media not coming through

• Verify the sender is in BLUEBUBBLES_ALLOWED_NUMBERS
• Check that the media file size is within the MAX_MEDIA_SIZE_BYTES limit (default 20 MB)
• Ensure BlueBubbles has Full Disk Access on the Mac

iMessage not activating on the Mac

• Some Apple IDs require two-factor authentication to be enabled
• Signing in from a cloud/datacenter IP (e.g. AWS Mac instances) may require extra verification
• Try signing out and back into iMessage in Messages > Settings > iMessage

Reference

See the Configuration page for the full list of BlueBubbles environment variables.