ADDING_A_PLATFORM.md 19 KB

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=<name> 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=<name> job fires correctly but the actual send returns No live adapter for platform '<name>'. 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(<platform>, 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/<platform>.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:<id>:<idx>, appr:<id>:<choice>, sc:<choice>:<id>) is shared across adapters — match it so the gateway-side resolvers work without modification.

Required function

def check_<platform>_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:

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.

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():

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:

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, ...):

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:

"hermes-your-platform": {
    "description": "Your Platform bot toolset",
    "tools": _HERMES_CORE_TOOLS,
    "includes": []
},

And add it to the hermes-gateway composite:

"hermes-gateway": {
    "includes": [..., "hermes-your-platform"]
}

8. Cron Delivery (cron/scheduler.py)

Add to platform_map in _deliver_result():

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():

platform_map = {
    ...
    "your_platform": Platform.YOUR_PLATFORM,
}

Add routing in _send_to_platform():

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:

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:

platforms = {
    ...
    "Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
}

13. Gateway Setup Wizard (hermes_cli/gateway.py)

Add to the _PLATFORMS list:

{
    "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/<platform>.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_<platform>.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:

# 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