Quartz 4

BlueBubbles iMessage Integration Hub

6 min read

BlueBubbles iMessage Integration Hub

Production-live status

This integration is ACTIVE. Per G-NO-PLAINTEXT-CREDS — this hub MUST NOT quote any credential values. All credentials referenced as op://Aurora/bluebubbles/<field> only.

BlueBubbles is the iMessage proxy layer in OpenClaw — a self-hosted Electron app running on the Mac Mini (NOT the EC2 Mac Ultra) that exposes a REST HTTP API and webhook dispatcher for iMessage send/receive. Aurora uses this integration to send and receive iMessages from the aurora@reri.co Apple ID on behalf of RERI conversations with sellers, buyers, and TCs. The 6-file KB is the richest in Wave 3. Read this hub when debugging missed iMessages, diagnosing Mac connectivity issues, or wiring new iMessage event handlers. KB last verified 2026-04-22.

Quick reference

FieldValue
VendorBlueBubbles (open-source, MIT)
URLhttps://bluebubbles.app
KB docAPI, WEBHOOKS, CREDENTIALS, INSTALLATION, INDEXING, PRIVATE-API
Auth methodQuery parameter ?password= (also accepted as ?guid= or ?token=). Simple string equality — no HMAC, no token expiry. Webhook auth: URL secret token (?secret=) — NOT HMAC (source: webhookService/index.ts).
Auth credentialop://Aurora/bluebubbles/server-password (API); op://Aurora/bluebubbles/webhook-secret (inbound webhook URL)
Cred-proxy portn/a (until NemoClaw B1-B6 ratified) — NOTE: password in URL query param is a high-priority cred-proxy candidate once B1 ratified
Webhook portNot on VPS directly — Mac Mini pushes inbound iMessage events to VPS webhook handler. Handler: webhooks/imessage-handler.js
Webhook handlerworkspace/webhooks/imessage-handler.js — inbound iMessage events from Mac Mini via Tailscale
Webhook dedup tableprocessed_webhook_events (24h TTL)
Tunnel pathInternal Tailscale only (Mac Mini → VPS via 100.x.x.x). NOT exposed via Cloudflare Tunnel or Tailscale Funnel.
Outbound API basehttp://100.80.204.89:1234/api/v1 (Mac Mini Tailscale IP, port 1234)
Rate limitsNone documented; Mac iMessage throughput is the practical limit
Rate-limit actionRetry with exponential backoff; Discord ops alert if Mac unreachable
CostFree (open-source). Apple ID required — uses existing aurora@reri.co Google Workspace account configured as Apple ID on Mac Mini.
Backup/recoveryMac-side: BlueBubbles config in ~/Library/Application Support/bluebubbles-server/config.db. Webhook registrations survive restarts. If Mac goes offline: iMessages queue on Apple servers and deliver when Mac comes back online.
Discord alert channelops
Drift cadenceWeekly (security-audit-funnel.timer) / on Mac restart
Statusproduction

Mac Mini infrastructure dependency

CRITICAL: BlueBubbles runs on the Mac Mini, NOT the EC2 Mac Ultra (100.123.248.46).

HostRoleStatus note
auroras-mac-mini (100.80.204.89)BlueBubbles server — iMessage proxyHostname unresolved as of last SESSION-AUDIT probe. Both auroras-mac-mini and auroras-mac-mini-2 were offline at last check (SESSION-AUDIT A1). Connectivity via Tailscale IP 100.80.204.89.
EC2 Mac Ultra (100.123.248.46)InvestorLift scraping ONLY — NOT BlueBubblesImpaired since 2026-05-02 22:15 UTC. See aws

Do NOT attempt BlueBubbles API calls to the EC2 Mac Ultra. They will fail. Always use 100.80.204.89:1234.

Components

  • workspace/knowledge-base/bluebubbles/API.md — Full HTTP API: endpoints, auth, message send/receive, chat management, contacts, server control; server v1.9.9 on Mac Mini
  • workspace/knowledge-base/bluebubbles/WEBHOOKS.md — Webhook registration, event types (new-message, updated-message, typing-indicator, etc.), fire-and-forget delivery, security (URL token recommended)
  • workspace/knowledge-base/bluebubbles/CREDENTIALS.md — Auth mechanism (source-verified from authMiddleware.ts), rotation procedures, Apple ID notes, Tailscale network topology
  • workspace/knowledge-base/bluebubbles/INSTALLATION.md — Mac setup, BlueBubbles Server app config, Private API helper bundle
  • workspace/knowledge-base/bluebubbles/INDEXING.md — Message indexing, iMessage database structure on Mac
  • workspace/knowledge-base/bluebubbles/PRIVATE-API.md — Private API capabilities (tapback reactions, typing indicators, read receipts — require Helper Bundle)
  • workspace/knowledge-base/bluebubbles/_audit/ — Audit trail for KB drift checks
  • workspace/webhooks/imessage-handler.js — VPS-side webhook handler for inbound iMessage events from Mac Mini
  • [[wiki/_hubs/integrations/openphone-quo]] — Parallel messaging channel (OpenPhone/Quo SMS); BB handles iMessage, Quo handles SMS — compare routing logic
  • [[wiki/_hubs/integrations/salesmsg]] — Third messaging channel (SalesMsg SMS broadcast); compare BB (1:1 iMessage) vs SalesMsg (broadcast)
  • [[wiki/_hubs/integrations/aws]] — Mac Mini is NOT EC2; but AWS context matters for understanding the two-Mac topology

How it’s used

  • Trigger condition: Seller, buyer, or TC sends iMessage to aurora@reri.co → BlueBubbles Server (Mac Mini) fires HTTP POST to VPS webhook handler at http://100.x.x.x:{port}/webhooks/bluebubbles?secret={token} → imessage-handler.js classifies message → routes to Aurora agent for response generation
  • Workflow: Aurora generates iMessage reply via mcp__aurora-orchestrator__reply_to_imessage or mcp__aurora-orchestrator__react_to_imessage → VPS calls POST /api/v1/message/text?password={token} to Mac Mini 100.80.204.89:1234 → BlueBubbles delivers via iMessage
  • Agents involved: Aurora (primary consumer — iMessage conversation orchestration). See _summary.
  • Failure mode: Mac Mini offline or BlueBubbles app crashed → webhook events stop arriving at VPS; outbound sends return connection refused from 100.80.204.89:1234. Diagnostic: curl "http://100.80.204.89:1234/api/v1/ping?password={token}" — should return {"data":"pong"}. If failure persists >24h → G-FAILED-SERVICE-MTTR applies.
  • Success criteria: GET /api/v1/ping returns {"data":"pong"}; inbound iMessage appears in imessage-handler.js logs; outbound send returns {"status":200} with "error":null.

Webhook security note

BlueBubbles does NOT sign webhook payloads with HMAC (source-verified from webhookService/index.ts — only Content-Type: application/json sent). Security is via:

  1. URL secret token (?secret=BLUEBUBBLES_WEBHOOK_SECRET) — read req.query.secret in handler and compare to stored value
  2. Tailscale network restriction — Mac Mini reaches VPS only via Tailscale; webhook URL should use VPS Tailscale IP

Per feedback_no_plaintext_creds: the webhook secret is stored in master.env as BLUEBUBBLES_WEBHOOK_SECRET and referenced as op://Aurora/bluebubbles/webhook-secret. Never hardcode.

Agents that touch this

  • _summary — primary iMessage conversation handler; uses reply_to_imessage and react_to_imessage MCP tools
  • _summary — may receive iMessage leads from sellers who prefer iMessage over SMS

Skills that invoke this

Plans that govern this

Feedback rules

KB / source docs

  • API — HTTP API full reference (v1, server v1.9.9)
  • WEBHOOKS — Webhook event types, delivery mechanics, security
  • CREDENTIALS — Auth mechanism, rotation, Apple ID, Tailscale topology
  • INSTALLATION — Mac setup guide
  • INDEXING — iMessage database structure
  • PRIVATE-API — Private API (Helper Bundle): reactions, typing, read receipts

System maps

BlueBubbles iMessage (this hub) and WhatsApp (whatsapp-imessage) form the Personal-messaging-mac cluster. BlueBubbles is PRODUCTION-LIVE — iMessage send/receive for aurora@reri.co on Mac Mini. WhatsApp is ASPIRATIONAL — planned integration, no production handler. Both contrast with OpenPhone/Quo (SMS/voice, VoIP-based) and SalesMsg (SMS broadcast). The cluster anchor is this hub (BlueBubbles) as the production-live representative.

All BlueBubbles credentials are in 1Password vault Aurora. Hub: 1password. Per G-NO-PLAINTEXT-CREDS — zero plaintext credentials in any tracked file. Reference as op://Aurora/bluebubbles/<field> only.

Open issues / TODOs

  • VERIFY: Confirm Mac Mini hostname (auroras-mac-mini vs auroras-mac-mini-2) — both were offline at last SESSION-AUDIT probe (A1). Ping 100.80.204.89 to confirm Tailscale connectivity.
  • VERIFY: Confirm imessage-handler.js is running and events are flowing via webhook_audit_log in Supabase
  • VERIFY: Private API Helper Bundle status on Mac Mini — needed for typing indicators and tapback reactions used by Aurora
  • MONITOR: BlueBubbles Server app auto-update may change API behavior — check /api/v1/server/update/check weekly
  • BLOCKER if Mac down >24h: G-FAILED-SERVICE-MTTR applies — escalate to ops

Recent activity

  • 2026-05-04: Hub created (Wave 3 W3-S6). PRODUCTION-LIVE status flagged. Mac Mini dependency documented. KB last_verified 2026-04-22 (most recent in Wave 3).

Graph View

Backlinks