# Adding a New Messaging Platform There are two ways to add a platform to the Hermes gateway: ## Plugin Path (Recommended for Community/Third-Party) Create a plugin directory in `~/.hermes/plugins/` (or under `plugins/platforms/` for bundled plugins) with a `plugin.yaml` and `adapter.py`. The adapter inherits from `BasePlatformAdapter` and registers via `ctx.register_platform()` in the `register(ctx)` entry point. This requires **zero changes to core Hermes code**. The plugin system automatically handles: adapter creation, config parsing, user authorization, cron delivery, send_message routing, system prompt hints, status display, gateway setup, and more. **Optional hooks cover the edges most adapters need:** - `env_enablement_fn: () -> Optional[dict]` — seeds `PlatformConfig.extra` (and an optional `home_channel` dict) from env vars BEFORE the adapter is constructed. Without this, env-only setups don't surface in `hermes gateway status` or `get_connected_platforms()` until the SDK instantiates. Build it from a `(ENV_VAR, extra_key, conv)` table with `gateway.platforms._shared.seed_extra_from_env(spec, home_env=...)`; every read goes through `_shared.get_scoped_secret` (multiplex-safe, never `os.getenv`). - `apply_yaml_config_fn: (yaml_cfg, platform_cfg) -> Optional[dict]` — translate this platform's `config.yaml` keys into env vars and seed `PlatformConfig.extra`. Lets a plugin own its YAML schema instead of growing core `gateway/config.py` boilerplate per platform. Declare a `(yaml_key, ENV_VAR, kind)` table and return `_shared.apply_yaml_bridge(platform_cfg, TABLE)`: it writes env only when unset (env > YAML), never under a multiplexed secondary profile's scope, and returns the same values for `extra` (read `extra` first in the adapter via `_shared.extra_or_secret`). Called during `load_gateway_config()` after the generic shared-key loop and before `_apply_env_overrides()`. - `is_connected: (config) -> bool` — for env-only platforms use `_shared.env_is_connected("YOUR_TOKEN_VAR", ...)` instead of a hand-rolled `get_env_value` check. - `cron_deliver_env_var: str` — name of the `*_HOME_CHANNEL` env var. When set, `deliver=` cron jobs route to this var without editing `cron/scheduler.py`'s hardcoded sets. - `standalone_sender_fn: async (...) -> dict`: out-of-process delivery for cron jobs that run separately from the gateway. Without this, a `deliver=` job fires correctly but the actual send returns `No live adapter for platform ''`. Pair with `cron_deliver_env_var` for end-to-end cron support. See the docsite for the signature. - `plugin.yaml` `requires_env` / `optional_env` rich-dict entries — auto-populate `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` so the setup wizard surfaces proper descriptions, prompts, password flags, and URLs. **Subclassing for platform-specific UX.** When a platform has a hard time-window constraint that the base adapter can't anticipate (LINE's 60s single-use reply token, WhatsApp's 24h session window, etc.), an adapter can override `_keep_typing` to layer a mid-flight bubble at a threshold without expanding the kwarg surface. Always `await super()._keep_typing(...)` so the typing heartbeat keeps running, and tear down your side task in `finally`. See `plugins/platforms/line/` for the full pattern (Template Buttons postback at 45s, `RequestCache` state machine, `interrupt_session_activity` override for `/stop` orphans) and the developer-guide page for the prose walkthrough. **Sibling adapters that share behavior.** When a single platform has two transport modes the user picks between — unofficial vs official APIs, polling vs websocket, library A vs library B — the right structure is two adapters that share a behavior mixin. WhatsApp does this: `plugins/platforms/whatsapp/adapter.py` (Baileys bridge) and `plugins/platforms/whatsapp_cloud/adapter.py` (Meta Cloud API) both inherit from `WhatsAppBehaviorMixin` in `gateway/platforms/whatsapp_common.py`. The mixin owns gating, allow-lists, mention parsing, broadcast filters, and the WhatsApp-flavored markdown conversion — everything that's platform-protocol-agnostic. Each adapter owns its transport. Both register distinct `Platform.*` enum values so the gateway can run both simultaneously against different phone numbers. The mixin must come **first** in the bases list — `class WhatsAppAdapter(Mixin, BasePlatformAdapter)` — so the mixin's `format_message` overrides `BasePlatformAdapter`'s generic default. See `plugins/platforms/irc/`, `plugins/platforms/teams/`, and `plugins/platforms/google_chat/` for complete working examples, and `website/docs/developer-guide/adding-platform-adapters.md` for the full plugin guide with code examples and hook documentation. --- Plugin-registered native handlers (`ctx.register_platform_handler(, factory)`): call `self._wire_plugin_handlers(native_client)` once in `connect()` before your own catch-all handlers. The base class then handles plugins that load mid-run — the runner calls `rewire_plugin_handlers()` on every plugin-loaded event and only factories not yet wired on that native client run. Override it only when your adapter keeps a second plugin registry (Slack action handlers) or dispatches by registration order with a catch-all last (Telegram hoists late handlers ahead of core); see `gateway/run_plugin_rewire.py`. ## Built-in Path (Core Contributors Only) Checklist for integrating a platform directly into the Hermes core. Use this as a reference when building a built-in adapter — every item here is a real integration point. Missing any of them will cause broken functionality, missing features, or inconsistent behavior. --- ## 1. Core Adapter (`gateway/platforms/.py`) The adapter is a subclass of `BasePlatformAdapter` from `gateway/platforms/base.py`. ### Required methods | Method | Purpose | |--------|---------| | `__init__(self, config)` | Parse config, init state. Call `super().__init__(config, Platform.YOUR_PLATFORM)` | | `connect() -> bool` | Connect to the platform, start listeners. Return True on success | | `disconnect()` | Stop listeners, close connections, cancel tasks | | `send(chat_id, text, ...) -> SendResult` | Send a text message | | `send_typing(chat_id)` | Send typing indicator | | `send_image(chat_id, image_url, caption) -> SendResult` | Send an image | | `get_chat_info(chat_id) -> dict` | Return `{name, type, chat_id}` for a chat | ### Optional methods (have default stubs in base) | Method | Purpose | |--------|---------| | `send_document(chat_id, path, caption)` | Send a file attachment | | `send_voice(chat_id, path)` | Send a voice message | | `send_video(chat_id, path, caption)` | Send a video | | `send_animation(chat_id, path, caption)` | Send a GIF/animation | | `send_image_file(chat_id, path, caption)` | Send image from local file | ### Interactive UX (recommended if your platform supports tappable buttons) If your platform supports interactive button/menu messages, implement these for a more polished agent experience. They all degrade gracefully to plain text when not overridden: | Method | Purpose | |--------|---------| | `send_clarify(chat_id, question, choices, clarify_id, session_key, ...)` | Render the `clarify` tool's multi-choice question as tappable buttons. Pair with inbound dispatch that routes button taps to `tools.clarify_gateway.resolve_gateway_clarify`. | | `_send_exec_approval_prompt(prompt: ExecApprovalPrompt)` | Render a dangerous-command approval as native buttons. `send_exec_approval` is a base template method: it builds the shared text (`_format_exec_approval`, tune via the `_EA_*` class attrs) and the choice set (`prompt.actions` = `(label, choice, style)` rows, choices `once`/`session`/`always`/`deny`) — you only map those rows to widgets. Inbound dispatch routes to `tools.approval.resolve_gateway_approval_card` with the card's request id (`prompt.request_id`), so a press answers the request that card showed. | | `send_slash_confirm(chat_id, title, message, session_key, confirm_id, ...)` | Render slash-command confirmations (e.g. `/reload-mcp`) as Once/Always/Cancel buttons. Inbound dispatch routes to `tools.slash_confirm.resolve`. | | `send_model_picker(...)` | Interactive `/model` picker. Used by Telegram, Discord, and Slack (Socket Mode). | | `send_choice_picker(...)` | Flat single-level picker for finite-choice commands (`/reasoning`, `/fast`). Implemented by Telegram (inline keyboard), Discord (select menu), Matrix (reactions), and Feishu (interactive card buttons). Platforms without it fall back to the text status card automatically. | See `plugins/platforms/telegram/adapter.py`, `plugins/platforms/discord/adapter.py`, and `plugins/platforms/whatsapp_cloud/adapter.py` for reference implementations. The button-callback id convention (`cl::`, `appr::`, `sc::`) is shared across adapters — match it so the gateway-side resolvers work without modification. ### Required function ```python def check__requirements() -> bool: """Check if this platform's dependencies are available.""" ``` ### Key patterns to follow - Use `self.build_source(...)` to construct `SessionSource` objects (never `SessionSource(...)` directly — the transport provenance and profile route are stamped there) - Derive every adapter-side session key (batching, per-chat queues, busy detection) through `self._event_session_key(event)` / `self._source_session_key(source)`, never the free `build_session_key()` — the seam keys in the owning profile's namespace under a multiplexed gateway; the advisory lint (`scripts/check_profile_scope_patterns.py`, pattern P32) flags both - Call `self.handle_message(event)` to dispatch inbound messages to the gateway - Use `MessageEvent`, `MessageType` from `gateway.platforms.event` and `SendResult` from base - Use `cache_image_from_bytes`, `cache_audio_from_bytes`, `cache_document_from_bytes` for attachments - Filter self-messages (prevent reply loops) - Drop redelivered inbound IDs with `MessageDeduplicator` (`gateway/platforms/helpers.py`) held as an adapter attribute; the runner's reconnect copies its live IDs into the rebuilt adapter, a hand-rolled cache starts empty - Filter sync/echo messages if the platform has them - Redact sensitive identifiers (phone numbers, tokens) in all log output - Implement reconnection with exponential backoff + jitter for streaming connections - Set `MAX_MESSAGE_LENGTH` if the platform has message size limits --- ## 2. Platform Enum (`gateway/config.py`) Add the platform to the `Platform` enum: ```python class Platform(Enum): ... YOUR_PLATFORM = "your_platform" ``` Env credentials reach the config through the plugin's own `gateway_env.py` (the template is `plugins/platforms/telegram/gateway_env.py`), passed to `ctx.register_platform` as `env_overrides=gateway_env.ENV_OVERRIDES` and `env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS`. Steps run in order; `EnvCred` (`gateway/platform_env.py`) enables the platform when the named env vars resolve and copies them into `extra`. Import only `gateway.*` there: core reads the file directly, without the adapter, when the plugin is not loaded. ```python ENV_ENABLE_CREDENTIALS = ("YOUR_PLATFORM_TOKEN",) ENV_OVERRIDES = ( EnvCred(Platform.YOUR_PLATFORM, ("YOUR_PLATFORM_TOKEN",), token="YOUR_PLATFORM_TOKEN"), home_step(Platform.YOUR_PLATFORM, "YOUR_PLATFORM_HOME_CHANNEL"), ) ``` Every read goes through `gateway/config.py::_getenv` (the active profile's secret scope when one is bound, `os.environ` otherwise). **Never `os.getenv` here and never write `os.environ`**: under `gateway.multiplex_profiles` the process env is the DEFAULT profile's, so a raw read enables your platform for the wrong profile with the wrong credentials, and a write pins one profile's policy process-wide (first profile wins). Adapter-side reads use `gateway.platforms._shared.get_scoped_secret` / `extra_or_secret`. If your platform is "configured" without a token/api_key (WhatsApp uses the `enabled` flag, Signal the `extra` dict), declare `config_connected_fn` on the entry; `get_connected_platforms()` reads it. --- ## 3. Adapter Factory (`gateway/run.py`) Add to `_instantiate_adapter()`: ```python elif platform == Platform.YOUR_PLATFORM: from gateway.platforms.your_platform import YourAdapter, check_your_requirements if not check_your_requirements(): logger.warning("Your Platform: dependencies not met") return None return YourAdapter(config) ``` `_create_adapter()` wraps this factory and binds every successful adapter to its `GatewayRunner`. Do not construct platform adapters in lifecycle call sites; startup and reconnect must keep using the wrapper so profile routing is wired before `connect()`. --- ## 4. Authorization Maps (`gateway/pairing.py`, `gateway/authz_mixin.py`) Declare the allowlist names in the plugin's `gateway_env.py` and pass them with `**gateway_env.AUTHZ`; pairing, the authz ladder, the dashboard and the startup policy gate read them from the entry, and from this file when the entry is missing (safe mode, plugin disabled) or a user plugin overriding yours omits them: ```python AUTHZ = { "allowed_users_env": "YOUR_PLATFORM_ALLOWED_USERS", "allow_all_env": "YOUR_PLATFORM_ALLOW_ALL_USERS", # optional: "allow_bots_env": "YOUR_PLATFORM_ALLOW_BOTS", # optional, adapters that gate DMs/groups themselves: "own_policy_env": ("..._DM_POLICY", "..._GROUP_POLICY"), } ``` `_is_user_authorized()` reads every gate through `_shared.platform_gate_env` (`_auth_env`), which answers from the routed profile's secret scope under multiplex — never add an `os.getenv` here. --- ## 5. Session Source (`gateway/session.py`) If your platform needs extra identity fields (e.g., Signal's UUID alongside phone number), add them to the `SessionSource` dataclass with `Optional` defaults, and update `to_dict()`, `from_dict()`, and `build_source()` in base.py. --- ## 6. System Prompt Hints (`platform_hint`) Declare `platform_hint=` on `ctx.register_platform` (keep the text in a light sibling such as `adapter_hint.py`) so the agent knows what platform it's on. `agent/prompt_builder.py::PLATFORM_HINTS` holds only core surfaces (CLI, TUI, API server, ...): ```python PLATFORM_HINT = ( "You are on Your Platform. " "Describe formatting capabilities, media support, etc." ) ``` Without this, the agent won't know it's on your platform and may use inappropriate formatting (e.g., markdown on platforms that don't render it). --- ## 7. Toolset (`toolsets.py`) Add a named toolset for your platform: ```python "hermes-your-platform": { "description": "Your Platform bot toolset", "tools": _HERMES_CORE_TOOLS, "includes": [] }, ``` And add it to the `hermes-gateway` composite: ```python "hermes-gateway": { "includes": [..., "hermes-your-platform"] } ``` --- ## 8. Cron Delivery (`cron/scheduler.py`) Add to `platform_map` in `_deliver_result()`: ```python platform_map = { ... "your_platform": Platform.YOUR_PLATFORM, } ``` Without this, `cronjob(action="create", deliver="your_platform", ...)` silently fails. --- ## 9. Send Message Tool (`tools/send_message_tool.py`) Add to `platform_map` in `send_message_tool()`: ```python platform_map = { ... "your_platform": Platform.YOUR_PLATFORM, } ``` Add routing in `_send_to_platform()`: ```python elif platform == Platform.YOUR_PLATFORM: return await _send_your_platform(pconfig, chat_id, message) ``` Implement `_send_your_platform()` — a standalone async function that sends a single message without requiring the full adapter (for use by cron jobs and the send_message tool outside the gateway process). Update the tool schema `target` description to include your platform example. --- ## 10. Cronjob Tool Schema (`tools/cronjob_tools.py`) Update the `deliver` parameter description and docstring to mention your platform as a delivery option. --- ## 11. Channel Directory (`gateway/channel_directory.py`) If your platform can't enumerate chats (most can't), add it to the session-based discovery list: ```python for plat_name in ("telegram", "whatsapp", "signal", "your_platform"): ``` --- ## 12. Status Display (`hermes_cli/status.py`) Add to the `platforms` dict in the Messaging Platforms section: ```python platforms = { ... "Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"), } ``` --- ## 13. Gateway Setup Wizard (`hermes_cli/gateway.py`) Add to the `_PLATFORMS` list: ```python { "key": "your_platform", "label": "Your Platform", "emoji": "📱", "token_var": "YOUR_PLATFORM_TOKEN", "setup_instructions": [...], "vars": [...], } ``` If your platform needs custom setup logic (connectivity testing, QR codes, policy choices), add a `_setup_your_platform()` function and route to it in the platform selection switch. Update `_platform_status()` if your platform's "configured" check differs from the standard `bool(get_env_value(token_var))`. --- ## 14. Phone/ID Redaction (`agent/redact.py`) If your platform uses sensitive identifiers (phone numbers, etc.), add a regex pattern and redaction function to `agent/redact.py`. This ensures identifiers are masked in ALL log output, not just your adapter's logs. --- ## 15. Documentation | File | What to update | |------|---------------| | `README.md` | Platform list in feature table + documentation table | | `AGENTS.md` | Gateway description + env var config section | | `website/docs/user-guide/messaging/.md` | **NEW** — Full setup guide (see existing platform docs for template) | | `website/docs/user-guide/messaging/index.md` | Architecture diagram, toolset table, security examples, Next Steps links | | `website/docs/reference/environment-variables.md` | All env vars for the platform | --- ## 16. Tests (`tests/gateway/test_.py`) Recommended test coverage: - Platform enum exists with correct value - Config loading from env vars via `_apply_env_overrides` - Adapter init (config parsing, allowlist handling, default values) - Helper functions (redaction, parsing, file type detection) - Session source round-trip (to_dict → from_dict) - Authorization integration (platform in allowlist maps) - Send message tool routing (platform in platform_map) Optional but valuable: - Async tests for message handling flow (mock the platform API) - SSE/WebSocket reconnection logic - Attachment processing - Group message filtering --- ## Quick Verification After implementing everything, verify with: ```bash # All tests pass python -m pytest tests/ -q # Grep for your platform name to find any missed integration points grep -r "telegram\|discord\|whatsapp\|slack" gateway/ tools/ agent/ cron/ hermes_cli/ toolsets.py \ --include="*.py" -l | sort -u # Check each file in the output — if it mentions other platforms but not yours, you missed it ```