flynn/docs/plans/2026-02-16-imessage-bluebubbles-channel-adapter-checklist.md

iMessage / BlueBubbles Channel Adapter Checklist

Date: 2026-02-16 Status: completed

Scope

• Add a first-class iMessage channel path via BlueBubbles.
• Support inbound webhook events and outbound text replies through the BlueBubbles API.

Completed

• Added BlueBubblesAdapter in src/channels/bluebubbles/adapter.ts:
  • inbound webhook handling for POST /bluebubbles/events
  • optional webhook token validation (bluebubbles.webhook_token)
  • allowlist support for chat GUIDs (allowed_chat_guids)
  • mention-aware group gating (require_mention, mention_name)
  • outbound text send via BlueBubbles REST endpoint
  • reply routing via metadata.replyPeerId
• Registered channel exports:
  • src/channels/bluebubbles/index.ts
  • src/channels/index.ts
• Added config schema support in src/config/schema.ts:
  • bluebubbles.endpoint
  • bluebubbles.api_key
  • bluebubbles.webhook_token
  • bluebubbles.allowed_chat_guids
  • bluebubbles.require_mention
  • bluebubbles.mention_name
• Wired daemon + gateway integration:
  • registration in src/daemon/channels.ts
  • gateway route wiring in src/gateway/server.ts (POST /bluebubbles/events)
• Updated service discovery + docs:
  • src/gateway/handlers/services.ts
  • README.md
  • config/default.yaml
  • docs/api/PROTOCOL.md
• Added tests:
  • src/channels/bluebubbles/adapter.test.ts
  • src/config/schema.test.ts (bluebubbles schema coverage)
  • src/gateway/handlers/services.test.ts (bluebubbles service status)

Verification

• pnpm test:run src/channels/bluebubbles/adapter.test.ts src/config/schema.test.ts src/gateway/handlers/services.test.ts
• pnpm typecheck