​

BlueBubbles (macOS REST)

​

Overview

• Runs on macOS via the BlueBubbles helper app (bluebubbles.app).
• Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync.
• Fased talks to it through its REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
• Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
• Pairing/allowlist works the same way as other channels (/channels/pairing etc) with channels.bluebubbles.allowFrom + pairing codes.
• Reactions are surfaced as system events just like Slack/Telegram so agents can “mention” them before replying.
• Advanced features: edit, unsend, reply threading, message effects, group management.

​

Quick start

1. Install the BlueBubbles server on your Mac (follow the instructions at bluebubbles.app/install).
2. In the BlueBubbles config, enable the web API and set a password.
3. Open Agents, select the Agent, then use Agent > Channels > BlueBubbles. Enter the server URL, password, and webhook path. Scripted setups can use config:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }
   
4. Point BlueBubbles webhooks to your gateway (example: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
5. Start or restart the gateway if the UI asks for it; it will register the webhook handler and start pairing.

• Always set a webhook password.
• Webhook authentication is always required. Fased rejects BlueBubbles webhook requests unless they include a password/guid that matches channels.bluebubbles.password (for example ?password=<password> or x-password), regardless of loopback/proxy topology.

​

Keeping Messages.app alive (VM / headless setups)

​

1) Save the AppleScript

• ~/Scripts/poke-messages.scpt

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

​

2) Install a LaunchAgent

• ~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

• This runs every 300 seconds and on login.
• The first run may trigger macOS Automation prompts (osascript → Messages). Approve them in the same user session that runs the LaunchAgent.

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

​

Alternate setup paths

fased onboard

• Server URL (required): BlueBubbles server address (e.g., http://192.168.1.100:1234)
• Password (required): API password from BlueBubbles Server settings
• Webhook path (optional): Defaults to /bluebubbles-webhook
• DM policy: pairing, allowlist, open, or disabled
• Allow list: Phone numbers, emails, or chat targets

fased channels add --channel bluebubbles --http-url http://192.168.1.100:1234 --password <password>

​

Access control (DMs + groups)

• Default: channels.bluebubbles.dmPolicy = "pairing".
• Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
• Approve via:
  • fased pairing list bluebubbles
  • fased pairing approve bluebubbles <CODE>
• Pairing is the default token exchange. Details: Pairing

• channels.bluebubbles.groupPolicy = open | allowlist | disabled (default: allowlist).
• channels.bluebubbles.groupAllowFrom controls who can trigger in groups when allowlist is set.

​

Mention gating (groups)

• Uses agents.list[].groupChat.mentionPatterns (or messages.groupChat.mentionPatterns) to detect mentions.
• When requireMention is enabled for a group, the agent only responds when mentioned.
• Control commands from authorized senders bypass mention gating.

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

​

Command gating

• Control commands (e.g., /config, /model) require authorization.
• Uses allowFrom and groupAllowFrom to determine command authorization.
• Authorized senders can run control commands even without mentioning in groups.

​

Typing + read receipts

• Typing indicators: Sent automatically before and during response generation.
• Read receipts: Controlled by channels.bluebubbles.sendReadReceipts (default: true).
• Typing indicators: Fased sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

​

Advanced actions

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

• react: Add/remove tapback reactions (messageId, emoji, remove)
• edit: Edit a sent message (messageId, text)
• unsend: Unsend a message (messageId)
• reply: Reply to a specific message (messageId, text, to)
• sendWithEffect: Send with iMessage effect (text, to, effectId)
• renameGroup: Rename a group chat (chatGuid, displayName)
• setGroupIcon: Set a group chat’s icon/photo (chatGuid, media) — flaky on macOS 26 Tahoe (API may return success but the icon does not sync).
• addParticipant: Add someone to a group (chatGuid, address)
• removeParticipant: Remove someone from a group (chatGuid, address)
• leaveGroup: Leave a group chat (chatGuid)
• sendAttachment: Send media/files (to, buffer, filename, asVoice)
  • Voice memos: set asVoice: true with MP3 or CAF audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.

​

Message IDs (short vs full)

• MessageSid / ReplyToId can be short IDs.
• MessageSidFull / ReplyToIdFull contain the provider full IDs.
• Short IDs are in-memory; they can expire on restart or cache eviction.
• Actions accept short or full messageId, but short IDs will error if no longer available.

• Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
• Context: MessageSidFull / ReplyToIdFull in inbound payloads

​

Block streaming

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

​

Media + limits

• Inbound attachments are downloaded and stored in the media cache.
• Media cap via channels.bluebubbles.mediaMaxMb (default: 8 MB).
• Outbound text is chunked to channels.bluebubbles.textChunkLimit (default: 4000 chars).

​

Configuration reference

• channels.bluebubbles.enabled: Enable/disable the channel.
• channels.bluebubbles.serverUrl: BlueBubbles REST API base URL.
• channels.bluebubbles.password: API password.
• channels.bluebubbles.webhookPath: Webhook endpoint path (default: /bluebubbles-webhook).
• channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• channels.bluebubbles.allowFrom: DM allowlist (handles, emails, E.164 numbers, chat_id:*, chat_guid:*).
• channels.bluebubbles.groupPolicy: open | allowlist | disabled (default: allowlist).
• channels.bluebubbles.groupAllowFrom: Group sender allowlist.
• channels.bluebubbles.groups: Per-group config (requireMention, etc.).
• channels.bluebubbles.sendReadReceipts: Send read receipts (default: true).
• channels.bluebubbles.blockStreaming: Enable block streaming (default: false; required for streaming replies).
• channels.bluebubbles.textChunkLimit: Outbound chunk size in chars (default: 4000).
• channels.bluebubbles.chunkMode: length (default) splits only when exceeding textChunkLimit; newline splits on blank lines (paragraph boundaries) before length chunking.
• channels.bluebubbles.mediaMaxMb: Inbound media cap in MB (default: 8).
• channels.bluebubbles.mediaLocalRoots: Explicit allowlist of absolute local directories permitted for outbound local media paths. Local path sends are denied by default unless this is configured. Per-account override: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
• channels.bluebubbles.historyLimit: Max group messages for context (0 disables).
• channels.bluebubbles.dmHistoryLimit: DM history limit.
• channels.bluebubbles.actions: Enable/disable specific actions.
• channels.bluebubbles.accounts: Multi-account configuration.

• agents.list[].groupChat.mentionPatterns (or messages.groupChat.mentionPatterns).
• messages.responsePrefix.

​

Addressing / delivery targets

• chat_guid:iMessage;-;+15555550123 (preferred for groups)
• chat_id:123
• chat_identifier:...
• Direct handles: +15555550123, [email protected]
  • If a direct handle does not have an existing DM chat, Fased will create one via POST /api/v1/chat/new. This requires the BlueBubbles Private API to be enabled.

​

Security

• Webhook requests are authenticated by comparing guid/password query params or headers against channels.bluebubbles.password. Requests from localhost are also accepted.
• Keep the API password and webhook endpoint secret (treat them like credentials).
• Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure gateway.trustedProxies. See Gateway security.
• Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.

​

Troubleshooting

• If typing/read events stop working, check the BlueBubbles webhook logs and verify the gateway path matches channels.bluebubbles.webhookPath.
• Pairing codes expire after one hour; use fased pairing list bluebubbles and fased pairing approve bluebubbles <code>.
• Reactions require the BlueBubbles private API (POST /api/v1/message/react); ensure the server version exposes it.
• Edit/unsend require macOS 13+ and a compatible BlueBubbles server version. On macOS 26 (Tahoe), edit is currently broken due to private API changes.
• Group icon updates can be flaky on macOS 26 (Tahoe): the API may return success but the new icon does not sync.
• Fased auto-hides known-broken actions based on the BlueBubbles server’s macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with channels.bluebubbles.actions.edit=false.
• For status/health info: fased status --all or fased status --deep.