Feature Specification — Powered by BlueBubbles + Docker
This spec defines a native iMessage integration for the Xavior platform, enabling users to send, receive, and AI-assist iMessages directly inside Xavior — using a dedicated Mac (e.g. iMac Studio) running BlueBubbles as the transport layer. Xavior runs in Docker. The result is a Gmail-equivalent experience for iMessage, with full AI drafting, contact linking, and conversation memory — entirely on the user's own infrastructure.
Apple's iMessage platform is deliberately closed — no public API, no OAuth, no web interface. This means the most personal and high-value conversations most users have (family, close friends, inner circle) are completely invisible to AI assistants. Email AI is ubiquitous. iMessage AI essentially does not exist.
For Xavior to be a true personal intelligence layer, it needs to see where real conversations happen. For most iPhone users, that's iMessage.
Xavior runs in Docker (docker-compose). BlueBubbles runs natively on a dedicated Mac (iMac Studio) on the same datacenter network. The two communicate over the internal network — no cloud intermediary.
Full data flow:
```
iMessage arrives on iMac Studio
→ BlueBubbles server detects it
→ Fires webhook → Docker host (nginx/Traefik)
→ Routed to Xavior agent container
→ Xavior stores message, links to contact
→ AI drafts a reply
→ User approves in Xavior UI
→ Xavior agent calls BlueBubbles REST API
→ iMac sends as real iMessage from user's number
```
Docker network considerations:
Minimal additions to the existing `docker-compose.yml`:
```yaml
services:
xavior-agent:
# existing service — no changes needed
environment:
BLUEBUBBLES_URL: http://192.168.x.x:1234 # Mac's datacenter IP
BLUEBUBBLES_API_KEY: your-api-key-here
# Optional: dedicated webhook receiver (if isolation preferred)
imessage-bridge:
image: xavior/imessage-bridge:latest
environment:
BLUEBUBBLES_URL: http://192.168.x.x:1234
BLUEBUBBLES_API_KEY: your-api-key-here
XAVIOR_INTERNAL_URL: http://xavior-agent:8100
ports:
- "5050:5050" # webhook ingress
```
Reverse proxy (nginx/Traefik) — add one route:
```nginx
location /webhooks/imessage {
proxy_pass http://xavior-agent:8100/webhooks/imessage;
}
```
BlueBubbles is then configured to POST to:
`https://your-xavior-domain.com/webhooks/imessage`
The Mac is the only non-containerized component. One-time setup:
1. Install BlueBubbles server app
2. Grant macOS permissions: Full Disk Access, Accessibility, Contacts
3. Log in with Apple ID (must match iMessage account)
4. In BlueBubbles settings:
- Set webhook URL → `https://your-xavior-domain.com/webhooks/imessage`
- Copy API key → paste into Xavior settings
5. Set Mac to never sleep (System Settings → Energy)
6. Set BlueBubbles as a Login Item (auto-starts on reboot)
7. Assign Mac a static IP on the datacenter network
After this, the Mac requires no further interaction. It runs silently as a transport layer.
From the user's perspective, setup mirrors connecting Gmail. BlueBubbles is invisible after initial config.
Settings → Integrations → iMessage → Connect
1. Step 1 — Install BlueBubbles on your Mac
Modal shows download link + checklist (permissions, Apple ID, never sleep). User completes on Mac.
2. Step 2 — Enter connection details
User pastes BlueBubbles server URL + API key (displayed in BlueBubbles dashboard).
3. Step 3 — Xavior verifies connection
Xavior pings BlueBubbles from within the agent container. On success:
✅ Connected — iMessage is ready.
4. Done. iMessage module appears in Xavior sidebar. All future operation is invisible to the user.
The iMessage module mirrors the Gmail module experience exactly:
Because Xavior has full workspace context, iMessage replies are far more intelligent than anything Apple or a generic AI could produce:
1. Apple ToS
BlueBubbles technically violates Apple's Terms of Service. Apple has not taken legal action against BlueBubbles users. Could restrict iMessage via macOS updates.
Mitigation: Power-user feature. Monitor BlueBubbles project. Skill is swappable if alternatives emerge.
2. macOS Update Breakage
Apple updates have broken BlueBubbles before — typically fixed within days by the BlueBubbles team.
Mitigation: Xavior health check monitors connection from inside the agent container. Push alert on failure. Graceful degradation — Xavior continues working, iMessage pauses.
3. Apple ID Session Expiry
Mac must stay logged into Apple ID.
Mitigation: BlueBubbles detects auth failure. Xavior surfaces alert prompting user to re-authenticate on Mac.
4. Network routing
BlueBubbles webhook must reach the Xavior container through the reverse proxy.
Mitigation: Single nginx/Traefik route addition. Static IP on Mac. No cloud dependency — all traffic stays on datacenter LAN.
5. Container restarts
If the Xavior agent container restarts, webhook connection persists (BlueBubbles keeps retrying). Messages queue and flush on reconnect.
No data available
Gmail vs iMessage integration — feature parity
Phase 1 — gog-imessage skill (1–2 weeks)
Build skill inside the Xavior agent container. Wraps BlueBubbles REST API: send, receive, webhook handler, contact resolution. Mirrors `gog-gmail` skill architecture.
Phase 2 — Webhook ingress (2–3 days)
Add `/webhooks/imessage` route to existing nginx/Traefik config. Wire into Xavior agent. Test end-to-end message flow from Mac → container → UI.
Phase 3 — Xavior UI module (1–2 weeks)
Build iMessage module in Xavior frontend. Thread view, draft panel, approve/send flow. Connection health indicator.
Phase 4 — AI layer (1 week)
Contextual drafting using workspace context. Tone matching baseline. Task creation from threads.
Phase 5 — Settings & onboarding (3–5 days)
Connect iMessage setup flow in Settings → Integrations. Health check ping from agent container. Push alerts for connection failures.
Phase 6 — Polish & advanced features (ongoing)
Conversation logging to Notes, nudges, group thread support, full-text search.