feat: BlueBubbles iMessage gateway adapter by benjaminsehl · Pull Request #5869 · NousResearch/hermes-agent

benjaminsehl · 2026-04-07T15:55:36Z

Summary

Adds Apple iMessage as a first-class messaging platform via the BlueBubbles macOS server. This follows the full ADDING_A_PLATFORM.md checklist.

Builds on the approach in #4588 by @1960697431, incorporating their media, reaction, typing indicator, and read receipt features while using a webhook-based architecture instead of polling.

How it works

Inbound: BlueBubbles sends webhook events to a local aiohttp listener (lower latency than polling, no deduplication needed)
Outbound: Hermes sends messages via the BlueBubbles REST API
Auth: Password-based, configured via BLUEBUBBLES_PASSWORD env var

Features

Text messaging — send and receive iMessages (DMs and group chats) with automatic markdown stripping
Rich media — images, voice messages, videos, documents, and GIFs via multipart upload
Tapback reactions — love, like, dislike, laugh, emphasize, question (requires Private API helper)
Typing indicators — send and stop typing status
Read receipts — automatically marks messages as read after processing
Chat GUID resolution — pass email addresses or phone numbers instead of raw BlueBubbles GUIDs
Private API safety — checks helper_connected status before using Private API features (avoids 500 errors when the helper isn't running)
Log redaction — phone numbers and emails masked in all log output

Integration points covered

File	What
`gateway/platforms/bluebubbles.py`	Core adapter (~480 lines)
`gateway/config.py`	Platform enum + env config loading
`gateway/run.py`	Adapter factory + authorization maps
`toolsets.py`	`hermes-bluebubbles` toolset + `hermes-gateway` composite
`tools/send_message_tool.py`	Platform routing + standalone `_send_bluebubbles()`
`cron/scheduler.py`	Cron delivery support
`gateway/channel_directory.py`	Session-based discovery
`agent/prompt_builder.py`	Platform hint for iMessage plain-text formatting
`hermes_cli/status.py`	Status display
`hermes_cli/gateway.py`	Setup wizard entry
`hermes_cli/tools_config.py`	Platform display config
`tools/cronjob_tools.py`	Cronjob tool schema
`tests/gateway/test_bluebubbles.py`	9 tests

Design differences from #4588

	This PR	#4588
Inbound	Webhooks (event-driven)	Polling (1.5s interval)
Chat addressing	Email/phone → GUID resolution	Raw GUIDs only
Private API	Checks `helper_connected`	Sends blindly (500 if helper down)
Naming	`Platform.BLUEBUBBLES`	`Platform.IMESSAGE`
Outbound formatting	Strips markdown	Passes through raw

Environment variables

BLUEBUBBLES_SERVER_URL=http://127.0.0.1:1234
BLUEBUBBLES_PASSWORD=<your-api-key>
BLUEBUBBLES_WEBHOOK_HOST=127.0.0.1
BLUEBUBBLES_WEBHOOK_PORT=8645
BLUEBUBBLES_HOME_CHANNEL=user@example.com
BLUEBUBBLES_ALLOWED_USERS=user@example.com,+15551234567

Test plan

pytest tests/gateway/test_bluebubbles.py — 9 tests pass
pytest tests/test_toolsets.py — 20 tests pass (including consistency checks)
End-to-end: inbound iMessage → AI response → outbound iMessage delivery verified on macOS with BlueBubbles Server v1.9.9

🤖 Generated with Claude Code

Adds full integration for Apple iMessage via the local BlueBubbles macOS server, following the ADDING_A_PLATFORM.md checklist: - Fix webhook to gracefully handle non-message events (typing, read receipts, group changes) instead of returning 400 errors - Track Private API helper connection status and only use private-api send method when the helper is actually connected (fixes 500 errors) - Add send_message tool routing and standalone _send_bluebubbles() - Add hermes-bluebubbles toolset and include in hermes-gateway - Add platform hint for iMessage plain-text formatting - Add cron scheduler delivery support - Add channel directory session-based discovery - Add status display, setup wizard entry, and cronjob tool schema - Fix tools_config default_toolset (was incorrectly set to hermes-signal) - Expand test coverage for payload extraction and webhook field resolution Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…adapter Incorporates features from PR NousResearch#4588 while keeping our webhook architecture and helper-connection safety checks: - Media attachments: send_image, send_voice, send_video, send_document, send_animation via BlueBubbles multipart upload API - Tapback reactions: send_reaction() with Private API helper guard - Typing indicators: send_typing() / stop_typing() with helper guard - Read receipts: mark_read() fired automatically after inbound messages - Log redaction: phone numbers and emails masked in log output - GUID cache: avoid repeated chat/query API calls per conversation - Enhanced get_chat_info: queries BlueBubbles for display names and participant lists instead of just inferring from the GUID - Skip inbound tapback reactions (associatedMessageType codes) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Without this, the gateway startup warning doesn't recognize BLUEBUBBLES_ALLOWED_USERS as a configured allowlist. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update setup wizard to recommend DM pairing as the primary auth method and make the allowlist optional, consistent with how other Hermes gateway platforms handle user authorization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…forms Platforms like iMessage/BlueBubbles don't support message editing, so each tool-use progress update was sent as a separate message bubble. Now sends a single "Working on it…" message instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Removes the hardcoded status message to avoid i18n concerns — platforms without message editing now silently skip tool progress updates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

@benjaminsehl

Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR #5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR #4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR #5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR #4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

teknium1 · 2026-04-09T06:54:37Z

Merged via PR #6437. Your webhook architecture, GUID resolution, Private API safety checks, and progress suppression for non-editable platforms were the foundation of the consolidated adapter. Thank you @benjaminsehl!

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

@benjaminsehl

…h#6437) Adds Apple iMessage as a gateway platform via BlueBubbles macOS server. Architecture: - Webhook-based inbound (event-driven, no polling/dedup needed) - Email/phone → chat GUID resolution for user-friendly addressing - Private API safety (checks helper_connected before tapback/typing) - Inbound attachment downloading (images, audio, documents cached locally) - Markdown stripping for clean iMessage delivery - Smart progress suppression for platforms without message editing Based on PR NousResearch#5869 by @benjaminsehl (webhook architecture, GUID resolution, Private API safety, progress suppression) with inbound attachment downloading from PR NousResearch#4588 by @1960697431 (attachment cache routing). Integration points: Platform enum, env config, adapter factory, auth maps, cron delivery, send_message routing, channel directory, platform hints, toolset definition, setup wizard, status display. 27 tests covering config, adapter, webhook parsing, GUID resolution, attachment download routing, toolset consistency, and prompt hints.

Sai and others added 8 commits April 7, 2026 11:54

Add BlueBubbles gateway adapter

4b883a7

fix: add BlueBubbles to startup allowlist/allow-all checks

07025f8

Without this, the gateway startup warning doesn't recognize BLUEBUBBLES_ALLOWED_USERS as a configured allowlist. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: replace personal email in tests with generic example.com

4884e23

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(gateway): drop "Working on it…" message, silently suppress instead

35a4fbe

Removes the hardcoded status message to avoid i18n concerns — platforms without message editing now silently skip tool progress updates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

teknium1 mentioned this pull request Apr 9, 2026

feat(gateway): add BlueBubbles iMessage platform adapter #6437

Merged

4 tasks

teknium1 closed this Apr 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: BlueBubbles iMessage gateway adapter#5869

feat: BlueBubbles iMessage gateway adapter#5869
benjaminsehl wants to merge 8 commits into
NousResearch:mainfrom
benjaminsehl:feat/bluebubbles-gateway

benjaminsehl commented Apr 7, 2026 •

edited

Loading

Uh oh!

teknium1 commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

benjaminsehl commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Features

Integration points covered

Design differences from #4588

Environment variables

Test plan

Uh oh!

teknium1 commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

benjaminsehl commented Apr 7, 2026 •

edited

Loading