BlueBubbles (iMessage)

iMessage integration via BlueBubbles macOS server with tapbacks, edit, unsend, message effects, group management, and voice memos.

BlueBubbles is OpenClaw's recommended path to iMessage integration, connecting your AI agent to Apple's messaging ecosystem through the BlueBubbles macOS server app. Unlike the legacy imsg channel that required direct chat.db access and complex permissions, BlueBubbles provides a clean REST API that OpenClaw talks to over HTTP — making setup significantly easier and the integration more reliable. The architecture requires a Mac running the BlueBubbles server app (available at bluebubbles.app). This Mac acts as a bridge between iMessage and OpenClaw: incoming iMessages arrive via webhooks, and outgoing replies are sent through REST API calls. This means your Mac needs to stay on and logged in, with Messages.app running. For headless/VM setups, a LaunchAgent that pokes Messages.app every 5 minutes prevents it from going idle. BlueBubbles supports an impressive range of iMessage features: tapback reactions (add and remove), message editing and unsend (macOS 13+), message effects (slam, loud, gentle, etc.), group management (rename, add/remove participants), voice memo support, and threading via reply-to. The integration handles media bidirectionally — your agent can send and receive images, videos, files, and stickers. The main constraint is the Mac requirement. You need a physical Mac (or macOS VM) running 24/7 with the BlueBubbles server. macOS Sequoia (15) is recommended and tested; macOS Tahoe (26) works but has some quirks (edit is currently broken, group icon updates may not sync). For Apple-ecosystem users who want their AI assistant in iMessage alongside their regular conversations, BlueBubbles is the clear choice over the deprecated imsg channel.

Tags: messaging, imessage, apple, macos

Category: Messaging

Use Cases

  • Personal AI assistant in iMessage — talk to your agent like any other contact
  • Family group chat assistant that answers questions when mentioned
  • iMessage-based notification system for important alerts
  • Apple ecosystem integration — Siri Shortcuts triggers + iMessage agent responses
  • Cross-platform messaging bridge — reach your OpenClaw agent from any Apple device

Tips

  • Use a dedicated Mac Mini as your always-on BlueBubbles + OpenClaw server
  • Set up the Messages.app LaunchAgent poke script from day one — it prevents the #1 reliability issue
  • Use Tailscale for secure remote access between OpenClaw and your Mac
  • Enable sendReadReceipts: true for a more natural conversation experience
  • Message effects (slam, loud, gentle) add personality to your agent's responses
  • Configure mention patterns for group chats so the agent only responds when addressed
  • Test the webhook connection with 'openclaw channels status --probe' before relying on it
  • Keep macOS and BlueBubbles updated, but test on a secondary setup first

Known Issues & Gotchas

  • The Mac running BlueBubbles must stay on and logged in 24/7 — screen lock is fine, but the user session must be active
  • Messages.app can go idle in VM/headless setups, causing missed incoming messages — use the LaunchAgent poke script
  • Always set a webhook password — OpenClaw rejects unauthenticated webhook requests regardless of network topology
  • macOS Tahoe (26) has known issues: message edit is broken, group icon updates may silently fail
  • BlueBubbles server and OpenClaw must be network-reachable — use Tailscale or Cloudflare Tunnel for remote setups
  • The first time you run the poke AppleScript, macOS will prompt for Automation permissions — approve them in the active user session
  • iMessage phone number format varies — some contacts use email, others use phone number
  • If Messages.app crashes or is force-quit, BlueBubbles needs it restarted to resume

Alternatives

  • iMessage (legacy imsg)
  • WhatsApp
  • Telegram

Community Feedback

BlueBubbles works fine for iMessages back and forth when the agent is awake, but I couldn't wake it up via iMessage like I can with WhatsApp. The Messages.app idle issue is real.

— Reddit r/openclaw

BlueBubbles is the best way to get iMessage on non-Apple devices. Pairing it with OpenClaw means your AI lives in the same app as your regular texts.

— Reddit r/BlueBubbles

Running BlueBubbles on a Mac Mini as my iMessage bridge. It's been surprisingly stable — the main gotcha is keeping Messages.app from sleeping.

— Reddit r/selfhosted

The tapback support is a nice touch. My agent can react to messages with thumbs up, heart, etc. Feels natural in iMessage conversations.

— Reddit r/openclaw

Frequently Asked Questions

Do I need a Mac to use BlueBubbles with OpenClaw?

Yes. BlueBubbles requires a Mac running macOS Sequoia (15) or later with Messages.app signed in. The Mac acts as a bridge between iMessage and OpenClaw. A Mac Mini is the most popular choice for an always-on server.

Can I run BlueBubbles in a macOS VM?

Yes, but with caveats. Messages.app can go idle in VM environments, causing missed messages. Set up the LaunchAgent poke script that touches Messages.app every 5 minutes to prevent this. macOS VMs also need proper Apple ID sign-in.

Should I use BlueBubbles or the legacy iMessage (imsg) channel?

Always use BlueBubbles for new setups. The legacy imsg channel is deprecated and has fewer features (no reactions, edits, effects, group management). BlueBubbles has a richer API and easier setup.

Why does my agent miss iMessages when my Mac is idle?

Messages.app can go idle in headless/VM setups, stopping incoming message events. Install the provided LaunchAgent that runs an AppleScript every 5 minutes to keep Messages.app responsive. This is the most common BlueBubbles reliability issue.

Does BlueBubbles support iMessage tapbacks (reactions)?

Yes. OpenClaw supports adding and removing tapback reactions through the BlueBubbles API. Your agent can react with love, like, dislike, laugh, emphasis, and question tapbacks.

Can I send message effects like 'slam' or 'loud'?

Yes. BlueBubbles integration supports iMessage effects including slam, loud, gentle, invisible ink, and more. Configure them in your agent's response behavior for a more expressive conversation style.

How do I set up webhooks between OpenClaw and BlueBubbles?

Configure BlueBubbles to send webhooks to your OpenClaw gateway URL (e.g., https://your-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD). Always include the password parameter — OpenClaw rejects unauthenticated webhook requests.

Configuration Examples

Basic local setup

channels:
  bluebubbles:
    enabled: true
    serverUrl: "http://192.168.1.100:1234"
    password: "your-password"
    webhookPath: "/bluebubbles-webhook"

Remote setup with Tailscale

channels:
  bluebubbles:
    enabled: true
    serverUrl: "http://100.64.0.5:1234"
    password: "your-password"
    webhookPath: "/bluebubbles-webhook"
    sendReadReceipts: true

Group-enabled with mention gating

channels:
  bluebubbles:
    enabled: true
    serverUrl: "http://192.168.1.100:1234"
    password: "your-password"
    webhookPath: "/bluebubbles-webhook"
    dmPolicy: pairing
    groupPolicy: allowlist
    groupAllowFrom:
      - "+15551234567"
    groups:
      "*":
        requireMention: true

Installation

Built-in (bundled with OpenClaw)