Why do I need a Mac for BlueBubbles?

iMessage is an Apple-only service that requires macOS and an Apple ID. BlueBubbles runs on the Mac to access the Messages framework directly. There's no way to connect to iMessage without a Mac — a dedicated Mac Mini or macOS VM is the typical setup for always-on operation.

What's the difference between BlueBubbles and the legacy iMessage channel?

BlueBubbles uses a modern REST API with webhook support, offering rich features like tapback reactions, message editing, effects, and group management. The legacy iMessage channel (imsg CLI) is deprecated and has limited functionality. BlueBubbles is the recommended approach for all new iMessage integrations.

Does BlueBubbles require the Private API?

The basic text messaging works without the Private API, but advanced features like tapback reactions, message editing, unsending, group management, and sending effects require the BlueBubbles Private API to be enabled. It's recommended to enable it for the full feature set.

Can I use BlueBubbles with multiple Apple IDs?

Each BlueBubbles server instance is tied to one Apple ID. If you need to bridge multiple Apple IDs, you'll need separate Mac instances running BlueBubbles, each configured as a different account in OpenClaw.

What happens if my Mac goes offline?

If the Mac running BlueBubbles goes offline, incoming iMessages will queue on Apple's servers. When the Mac comes back online, queued messages will be delivered. However, webhook events during the downtime are lost — the Gateway won't receive those notifications. Messages sent during downtime will appear in Messages.app but won't trigger AI responses.

How do pairing codes work?

When dmPolicy is 'pairing' (the default), unknown senders receive a random pairing code when they first message the bot. The code expires after 1 hour. Approve via 'openclaw pairing approve bluebubbles ' in your terminal. Once approved, the sender can chat freely without further verification.

OpenClaw GuideOpenClaw

Get Started

OpenClaw BlueBubbles Channel

Messaging

Medium

Connect OpenClaw to iMessage through the BlueBubbles REST API. This integration turns your Mac into an iMessage gateway — install the BlueBubbles server app, enable the web API, and your AI assistant can send and receive iMessages, tapback reactions, and media attachments. BlueBubbles is the recommended iMessage channel, replacing the legacy imsg CLI approach.

Quick Info

DifficultyMedium

CategoryMessaging

Features Supported4 / 6

BlueBubbles Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Supported

BlueBubbles Prerequisites

A Mac running macOS High Sierra (10.13) or later (Ventura 13+ recommended for full feature set; Tahoe 26 supported with limitations)
BlueBubbles server app installed from bluebubbles.app
Web API enabled with a password set in BlueBubbles configuration
OpenClaw Gateway running and configured

BlueBubbles Quick Setup

Install BlueBubbles server on your Mac

Download and install the BlueBubbles server application from bluebubbles.app/install. Launch the app, sign in with your Apple ID, and complete the initial setup. Make sure iMessage is active and working on the Mac.

Enable the Web API

In BlueBubbles server settings, enable the Web/REST API and set a strong password. Note the server URL (e.g., http://localhost:1234) — you'll need this for the OpenClaw config.

Add BlueBubbles channel config

Run 'openclaw onboard' and select BlueBubbles, or manually add the channel configuration to ~/.openclaw/openclaw.json with your serverUrl and password. Configure the webhookPath if needed.

Configure webhook and test

Point BlueBubbles webhooks to your Gateway: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Start the Gateway and send a test iMessage to verify the connection. If using pairing policy, approve the sender via 'openclaw pairing approve bluebubbles <code>'.

BlueBubbles Configuration Example

config.json

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles Deep Dive

Architecture Overview

OpenClaw connects to iMessage through the BlueBubbles server application running on a Mac. BlueBubbles exposes a REST API that the Gateway uses to send messages, reactions, and manage chats. Incoming messages are delivered via webhooks — BlueBubbles pushes new message events to the Gateway's webhook endpoint. The architecture flow is: iMessage arrives on Mac → BlueBubbles server → Webhook push to Gateway → OpenClaw processes with AI → REST API call back to BlueBubbles → iMessage delivered. This approach requires a Mac that stays online (physical or VM), since iMessage is an Apple-only service. The Mac acts as the bridge between Apple's messaging ecosystem and your OpenClaw assistant.

A dedicated Mac Mini or a macOS VM is ideal for running BlueBubbles as a persistent iMessage gateway.

BlueBubbles supports the Private API for advanced features like tapback reactions, message editing, and unsending — ensure it's enabled in the BlueBubbles settings.

BlueBubbles Server Setup

Setting up BlueBubbles requires installing the server application on your Mac: 1. Download BlueBubbles from bluebubbles.app/install and launch the application. 2. Sign in with your Apple ID and ensure iMessage is working on the Mac. 3. In BlueBubbles settings, enable the Web/REST API. 4. Set a strong API password — this authenticates all API requests and webhook deliveries. 5. Note the server URL displayed in the app (default: http://localhost:1234). 6. Optionally enable the Private API for advanced features (reactions, edit, unsend). The server must remain running for the iMessage bridge to work. Configure BlueBubbles to launch at startup for reliability.

webhook URL

# Webhook URL format for your Gateway
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD

Keep your BlueBubbles API password secure. If running on a network-exposed server, enable HTTPS on BlueBubbles and use firewall rules to restrict access. Same-host reverse proxies bypass password authentication — add proxy-level auth and configure gateway.trustedProxies.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant via iMessage. OpenClaw supports four policies: • pairing (default) — Unknown senders receive a time-limited pairing code (expires after 1 hour). You approve or deny via 'openclaw pairing approve bluebubbles <CODE>'. Once approved, they can chat freely. • allowlist — Only phone numbers and email addresses listed in allowFrom can message the bot. Everyone else is silently ignored. Supports E.164 format for phone numbers. • open — Anyone who messages gets a response. Use with caution. • disabled — DM handling is completely turned off.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}

The allowFrom field accepts both phone numbers (E.164 format like +15551234567) and email addresses for iMessage routing.

Group Chat Management

OpenClaw supports iMessage group chats through BlueBubbles with flexible access control: • groupPolicy controls who can trigger the bot in group chats: - open — Any group member can interact - allowlist — Only addresses listed in groupAllowFrom can trigger the bot - disabled (default) — Group messages are ignored • Mention gating — When requireMention is true (default for groups), the bot only responds when mentioned by name. Mention patterns are configured in agents.list[].groupChat.mentionPatterns. • Per-group configuration — Use the groups object to set different requireMention rules for specific group chats.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

iMessage Actions & Effects

BlueBubbles exposes a rich set of iMessage-native actions through the Private API. Each action can be individually toggled: • reactions — Send and receive tapback reactions (love, like, dislike, laugh, emphasis, question) • edit — Modify sent messages (requires macOS 13+; currently broken on macOS Tahoe) • unsend — Remove sent messages (macOS 13+) • reply — Thread messages by GUID for conversation threading • sendWithEffect — Send messages with iMessage bubble effects (slam, loud, gentle, invisible ink, etc.) • sendAttachment — Send media files and voice memos (MP3/CAF format for voice; BlueBubbles handles MP3→CAF conversion) Group management actions: • renameGroup — Rename group chat display names • setGroupIcon — Set group chat photos (flaky on macOS Tahoe) • addParticipant / removeParticipant / leaveGroup — Manage group membership

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}

On macOS Tahoe (26), the edit action is currently broken due to Private API changes, and setGroupIcon is unreliable (API returns success but icon doesn't sync). Disable these actions manually if you're running Tahoe.

Message Delivery & Chunking

OpenClaw handles outbound message delivery with configurable chunking for long AI responses: • textChunkLimit — Maximum characters per message chunk (default: 4000). iMessage has no strict limit, but long messages may not display well on all devices. • chunkMode — Controls how text is split: - length (default) — Hard split at textChunkLimit characters - newline — Split at paragraph boundaries for more natural reading • blockStreaming — When true, responses are sent in block-based chunks as they're generated, rather than waiting for the complete response. Read receipts are sent by default to maintain natural conversation flow. Typing indicators are automatically sent before and during AI response generation.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

Media & Attachments

BlueBubbles supports sending and receiving media through iMessage: • Inbound attachments are automatically downloaded and cached by the Gateway. The maximum inbound file size is controlled by mediaMaxMb (default: 8 MB). • Voice memos can be sent with the sendAttachment action using asVoice: true. BlueBubbles handles MP3→CAF conversion automatically for proper iMessage voice memo playback. • Outbound media is sent via the sendAttachment action with buffer, filename, and optional mime type parameters.

For voice memos, use MP3 or CAF format. BlueBubbles will convert MP3 to CAF automatically for native iMessage playback.

Adjust mediaMaxMb if you need to handle larger attachments — the default 8 MB covers most photos and short videos.

Message ID Handling

BlueBubbles uses two types of message identifiers: • Short IDs — In-memory tokens (like 1, 2, 3) that are fast but ephemeral. These expire on Gateway restart or cache eviction. • Full IDs — Persistent provider identifiers (MessageSidFull, ReplyToIdFull) that survive restarts and are stable for long-term reference. Both formats are accepted in action parameters (messageId, replyTo, etc.). For durable automations and integrations that need to reference messages across restarts, always use full IDs.

Use full message IDs for any automation that needs to survive Gateway restarts. Short IDs are convenient for interactive use but will break after a restart.

Addressing & Routing

BlueBubbles supports multiple addressing formats for message delivery. The preferred order for routing (most stable first): 1. chat_guid — Most stable format: chat_guid:iMessage;-;+15555550123 2. chat_id — Numeric chat identifier: chat_id:123 3. chat_identifier — Chat identifier string 4. Direct handles — Phone number (+15555550123) or email (user@example.com) When sending to a direct handle that doesn't have an existing chat, BlueBubbles automatically creates a new DM via POST /api/v1/chat/new (requires Private API).

Use chat_guid format for the most reliable message routing, especially in automations.

Security & Webhook Authentication

BlueBubbles authenticates webhook deliveries using the configured password. The Gateway verifies the password parameter (via query string or header) against your configured channels.bluebubbles.password. Security considerations: • Localhost requests are auto-trusted and bypass password verification. • Same-host reverse proxies also bypass password checks — if you're using a reverse proxy on the same machine, add proxy-level authentication and configure gateway.trustedProxies. • Enable HTTPS on the BlueBubbles server for encrypted communication. • Use firewall rules to restrict external access to the BlueBubbles API port. For production deployments, always use HTTPS and ensure the webhook endpoint is not publicly accessible without authentication.

Same-host reverse proxies bypass BlueBubbles password authentication. Always configure proxy-level auth and set gateway.trustedProxies when using a reverse proxy.

Messages.app Keepalive (Headless/VM)

If running BlueBubbles on a headless Mac or VM, the Messages.app may go idle and stop processing messages. The solution is a LaunchAgent that executes an AppleScript every 5 minutes to touch the Messages scripting interface. This keepalive script safely ignores transient failures and doesn't steal focus from other applications. It's essential for reliable unattended operation of the iMessage bridge. Set up a macOS LaunchAgent plist that runs the AppleScript at regular intervals to keep the Messages.app responsive.

This is only needed for headless/VM setups. If your Mac has an active desktop session with Messages.app visible, the keepalive is not necessary.

Use launchctl to manage the LaunchAgent — load it on boot for fully unattended operation.

BlueBubbles Configuration Reference

Key	Type	Default	Description
enabled	boolean	false	Enable or disable the BlueBubbles channel
serverUrl	string	""	BlueBubbles REST API base URL (e.g., http://localhost:1234)
password	string	""	BlueBubbles API password for authentication
webhookPath	string	"/bluebubbles-webhook"	Webhook endpoint path for receiving incoming messages
dmPolicy	string	"pairing"	Controls who can DM the bot. Options: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Phone numbers and emails allowed to message the bot (E.164 format for phones)
groupPolicy	string	"allowlist"	Group chat policy. Options: open, allowlist, disabled
groupAllowFrom	string[]	[]	Authorized sender addresses for triggering the bot in group chats
sendReadReceipts	boolean	true	Send read receipt confirmation when processing messages
blockStreaming	boolean	false	Enable block-based response streaming instead of waiting for complete response
textChunkLimit	number	4000	Maximum characters per outbound text message chunk
chunkMode	string	"length"	Text splitting mode. Options: length (size-based), newline (paragraph-based)
mediaMaxMb	number	8	Maximum inbound attachment file size in megabytes
historyLimit	number	-	Maximum group messages included as AI context (0 disables)
dmHistoryLimit	number	-	DM conversation history limit for AI context
actions.reactions	boolean	true	Enable tapback reactions (requires Private API)
actions.edit	boolean	true	Enable message editing (requires macOS 13+; broken on Tahoe)
actions.unsend	boolean	true	Enable message unsending (requires macOS 13+)
actions.reply	boolean	true	Enable message threading by GUID
actions.sendWithEffect	boolean	true	Enable iMessage bubble effects (slam, loud, gentle, etc.)
actions.sendAttachment	boolean	true	Enable media and voice memo delivery

enabled

Type: booleanDefault: false

Enable or disable the BlueBubbles channel

serverUrl

Type: stringDefault: ""

BlueBubbles REST API base URL (e.g., http://localhost:1234)

password

Type: stringDefault: ""

BlueBubbles API password for authentication

webhookPath

Type: stringDefault: "/bluebubbles-webhook"

Webhook endpoint path for receiving incoming messages

dmPolicy

Type: stringDefault: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom

Type: string[]Default: []

Phone numbers and emails allowed to message the bot (E.164 format for phones)

groupPolicy

Type: stringDefault: "allowlist"

Group chat policy. Options: open, allowlist, disabled

groupAllowFrom

Type: string[]Default: []

Authorized sender addresses for triggering the bot in group chats

sendReadReceipts

Type: booleanDefault: true

Send read receipt confirmation when processing messages

blockStreaming

Type: booleanDefault: false

Enable block-based response streaming instead of waiting for complete response

textChunkLimit

Type: numberDefault: 4000

Maximum characters per outbound text message chunk

chunkMode

Type: stringDefault: "length"

Text splitting mode. Options: length (size-based), newline (paragraph-based)

mediaMaxMb

Type: numberDefault: 8

Maximum inbound attachment file size in megabytes

historyLimit

Type: numberDefault: -

Maximum group messages included as AI context (0 disables)

dmHistoryLimit

Type: numberDefault: -

DM conversation history limit for AI context

actions.reactions

Type: booleanDefault: true

Enable tapback reactions (requires Private API)

actions.edit

Type: booleanDefault: true

Enable message editing (requires macOS 13+; broken on Tahoe)

actions.unsend

Type: booleanDefault: true

Enable message unsending (requires macOS 13+)

actions.reply

Type: booleanDefault: true

Enable message threading by GUID

actions.sendWithEffect

Type: booleanDefault: true

Enable iMessage bubble effects (slam, loud, gentle, etc.)

actions.sendAttachment

Type: booleanDefault: true

Enable media and voice memo delivery

BlueBubbles Frequently Asked Questions

BlueBubbles Troubleshooting

Webhook not receiving messages

The webhook URL in BlueBubbles doesn't match the Gateway endpoint, or the password parameter is incorrect.

Verify the webhook URL is set to https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD. Check that channels.bluebubbles.webhookPath matches the path in the URL. Review Gateway logs for incoming webhook attempts.

Gateway connects but actions fail (reactions, edit, unsend)

The BlueBubbles Private API is not enabled, or the server version doesn't support the required API endpoints.

Enable the Private API in BlueBubbles server settings. Update BlueBubbles to the latest version. If specific actions fail on macOS Tahoe, disable them individually: channels.bluebubbles.actions.edit=false.

Messages.app stops responding on headless Mac

Messages.app goes idle on headless/VM setups and stops processing the scripting interface.

Set up the AppleScript keepalive LaunchAgent to touch the Messages scripting interface every 5 minutes. Ensure the LaunchAgent is loaded via launchctl and runs on boot.

Bot sends messages but they don't appear as iMessages (green bubbles)

The recipient's phone number or email is not registered with iMessage, or the Apple ID on the Mac has iMessage disabled.

Verify iMessage is enabled in Messages.app preferences on the Mac. Check that the recipient uses an Apple device with iMessage enabled. Green bubbles indicate SMS fallback, which BlueBubbles may or may not support depending on configuration.

Edit action fails on macOS Tahoe

Known issue — macOS Tahoe (26) broke the Private API endpoint for message editing.

Disable the edit action: set channels.bluebubbles.actions.edit to false. This is a known BlueBubbles limitation on Tahoe. Monitor BlueBubbles releases for a fix.

View Full Documentation Back to All Channels