BlueBubbles (macOS REST)
Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. Recommended for iMessage integration due to its richer API and easier setup compared to the legacy imsg channel.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.
- WednesdayAI 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/pairingetc) withchannels.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
- Install the BlueBubbles server on your Mac (follow the instructions at bluebubbles.app/install).
- In the BlueBubbles config, enable the web API and set a password.
-
Run
wednesdayai onboardand select BlueBubbles, or configure manually: -
Point BlueBubbles webhooks to your gateway (example:
https://your-gateway-host:3000/bluebubbles-webhook?password=<password>). - Start the gateway; it will register the webhook handler and start pairing.
- Always set a webhook password.
- Webhook authentication is always required. WednesdayAI rejects BlueBubbles webhook requests unless they include a password/guid that matches
channels.bluebubbles.password(for example?password=<password>orx-password), regardless of loopback/proxy topology. - Password authentication is checked before reading/parsing full webhook bodies.
Keeping Messages.app alive (VM / headless setups)
Some macOS VM / always-on setups can end up with Messages.app going “idle” (incoming events stop until the app is opened/foregrounded). A simple workaround is to poke Messages every 5 minutes using an AppleScript + LaunchAgent.1) Save the AppleScript
Save this as:~/Scripts/poke-messages.scpt
2) Install a LaunchAgent
Save this as:~/Library/LaunchAgents/com.user.poke-messages.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.
Onboarding
BlueBubbles is available in the interactive setup wizard:- 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
Access control (DMs + groups)
DMs:- Default:
channels.bluebubbles.dmPolicy = "pairing". - Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
- Approve via:
wednesdayai pairing list bluebubbleswednesdayai pairing approve bluebubbles <CODE>
- Pairing is the default token exchange. Details: Pairing
channels.bluebubbles.groupPolicy = open | allowlist | disabled(default:allowlist).channels.bluebubbles.groupAllowFromcontrols who can trigger in groups whenallowlistis set.
Mention gating (groups)
BlueBubbles supports mention gating for group chats, matching iMessage/WhatsApp behavior:- Uses
agents.list[].groupChat.mentionPatterns(ormessages.groupChat.mentionPatterns) to detect mentions. - When
requireMentionis enabled for a group, the agent only responds when mentioned. - Control commands from authorized senders bypass mention gating.
Command gating
- Control commands (e.g.,
/config,/model) require authorization. - Uses
allowFromandgroupAllowFromto 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: WednesdayAI sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).
Advanced actions
BlueBubbles supports advanced message actions when enabled in config:- 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: truewith MP3 or CAF audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
- Voice memos: set
Message IDs (short vs full)
WednesdayAI may surface short message IDs (e.g.,1, 2) to save tokens.
MessageSid/ReplyToIdcan be short IDs.MessageSidFull/ReplyToIdFullcontain 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/ReplyToIdFullin inbound payloads
Block streaming
Control whether responses are sent as a single message or streamed in blocks: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
Full configuration: Configuration Provider options: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 exceedingtextChunkLimit;newlinepacks paragraph/block boundaries up totextChunkLimit;paragraphemits one message per paragraph. Fenced code blocks and tables are kept intact.channels.bluebubbles.chunkNewlinePackingis deprecated (default:true). PreferchunkMode: "paragraph"(false≡ that mode).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.channels.bluebubbles.configWrites: Allow channel-initiated config writes (default: true).channels.bluebubbles.ackReaction: Per-channel ack reaction emoji override.channels.bluebubbles.ackReactionScope: Scope for ack reactions (default:group-mentions).channels.bluebubbles.responsePrefix: Per-channel outbound response prefix override.
agents.list[].groupChat.mentionPatterns(ormessages.groupChat.mentionPatterns).messages.responsePrefix.
Inbox ingestion
Channel config alone never ingests BlueBubbles messages into the inbox. Inbox ingestion is opt-in per source: setinbox.sources.bluebubbles.enabled: true (default: off). This gates
both live dual-write mirroring of new messages AND the history scanner. Existing inbox rows
are never removed when the source is disabled or removed from config.
The live dual-write mirror fires through message_received, which runs after the channel’s
group gate: group messages dropped by groupPolicy/groupAllowFrom never reach the live
mirror. The history scanner (REST polling) is independent of the allowlist and still ingests
them. To mirror group traffic live, the senders must pass the channel allowlist (or
groupPolicy: "open").
Backfill history
With inbox ingestion enabled,wednesdayai inbox backfill --source bluebubbles [--account <id>] [--since <iso>] [--all] pulls the server’s message history into the
inbox store — manual, resumable, per-page checkpointed (see
Inbox API). The agent equivalent is the inbox.backfill
tool.
- The walk is global across chats — one checkpoint per account covering complete
history — reusing the live history scanner’s after-anchor walk (
POST /api/v1/message/querywithwith: ["chat"], ascending order, 100 messages per page, 30 s request timeout) and its thread-key normalization. No per-chat checkpoints. - The resume position is the scanner’s ms-epoch after-anchor; pages advance it until an
empty page ends the walk. Two degenerate pages never end it silently: a FULL page whose
messages share one timestamp cannot advance the anchor (the upstream
afteranchor is inclusive) and throws instead of certifying completion — the checkpoint stays resumable, so re-running resumes at the same position; likewise a non-empty page where no message maps (typically a missing chat join) throws rather than ending the walk. Clean termination is a genuinely empty page, or a partial page whose returned cursor equals the current position (nothing newer than the inclusive anchor remains).--since <iso>seeds the anchor at that timestamp;--allrestarts from the beginning of history. - Accounts come from the enabled scan targets (channel root config as the default
account, or
channels.bluebubbles.accounts). Theinbox.sources.bluebubbles.enabledgate applies here too: with it unset, backfill reports the source as not enabled — channel config alone never implies backfill.
Addressing / delivery targets
Preferchat_guid for stable routing:
chat_guid:iMessage;-;+15555550123(preferred for groups)chat_id:123chat_identifier:...- Direct handles:
+15555550123,user@example.com- If a direct handle does not have an existing DM chat, WednesdayAI will create one via
POST /api/v1/chat/new. This requires the BlueBubbles Private API to be enabled.
- If a direct handle does not have an existing DM chat, WednesdayAI will create one via
Security
- Webhook requests are authenticated by comparing
guid/passwordquery params or headers againstchannels.bluebubbles.password. Requests fromlocalhostare 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
wednesdayai pairing list bluebubblesandwednesdayai 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.
- WednesdayAI 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:
wednesdayai status --allorwednesdayai status --deep.