# 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`