hermes-chatto-plugin/plugin.yaml

name: chatto-platform
label: Chatto
kind: platform
version: main
description: >
  Chatto gateway adapter for Hermes Agent.
  Connects to a Chatto server (cloud-hosted or self-hosted team chat) and relays messages
  between rooms/DMs and the Hermes agent. Uses the Chatto ConnectRPC API
  (JSON over HTTP) for outbound messages and the Chatto realtime WebSocket
  protocol (binary protobuf) for inbound events.  Nothing to install:
  chattolib[realtime] and its dependencies are vendored into the plugin.
author: Paul Klumpp
provides_tools:
  - chatto_send_dm
  - chatto_send_room
  - chatto_send_ephemeral
  - chatto_list_rooms
  - chatto_get_message
  - chatto_get_history
  - chatto_search_messages
  - chatto_list_room_attachments
  - chatto_list_pinned_messages
  - chatto_pin_message
  - chatto_set_custom_status
  - chatto_delete_custom_status
  - chatto_fetch_link_preview
  - chatto_mark_thread_as_read
  - chatto_list_room_groups
requires_env:
  - name: CHATTO_BASE_URL
    description: "Base URL of the Chatto server (e.g. https://chat.example.com) leave blank for ChattoHQ (https://chat.chatto.run)"
    prompt: "Chatto server Base URL"
    password: false
  - name: CHATTO_TOKEN
    description: "Bot API key (e.g. cht_BK_...) — generate one in Chatto under Settings → Bot Accounts"
    prompt: "Chatto bot token"
    password: true
optional_env:
  - name: CHATTO_HOME_CHANNEL
    description: "Room ID for cron / notification delivery (default: none — context-less deliveries are not sent without it)"
    prompt: "Home room ID (or empty)"
    password: false
  # Asked before CHATTO_ALLOWED_USERS: a "yes" here makes the user list moot,
  # and the two are mutually exclusive (hermes_validate_config rejects both).
  - name: CHATTO_ALLOW_ALL_USERS
    description: "Allow any Chatto user to talk to the agent (default: false)"
    prompt: "Allow all users? (true/false)"
    password: false
  - name: CHATTO_ALLOWED_USERS
    description: "Comma-separated Chatto logins or user IDs allowed to talk to the agent (default: none — denies everyone unless CHATTO_ALLOW_ALL_USERS=true)"
    prompt: "Allowed users (comma-separated)"
    password: false
  - name: CHATTO_REQUIRE_MENTION_ROOMS
    description: "Comma-separated room IDs where the bot answers only when addressed (@name, @all or @here); rooms on neither this nor CHATTO_OPTIONAL_MENTION_ROOMS stay silent — read-only, never seeded into context, never answered. DMs always get a response. (default: none — the listed rooms answer only mentions)"
    prompt: "Mention-required room IDs (comma-separated)"
    password: false
  - name: CHATTO_AUTO_THREAD
    description: "Auto-create threads for replies in rooms (default: true). Set false to reply in the room timeline."
    prompt: "Auto-thread replies? (true/false)"
    password: false
  - name: CHATTO_OPTIONAL_MENTION_ROOMS
    description: "Comma-separated room IDs where the bot answers every message, addressed or not; rooms on neither this nor CHATTO_REQUIRE_MENTION_ROOMS stay silent — read-only, never seeded into context, never answered. (default: none — the listed rooms answer everything)"
    prompt: "Free-response room IDs (comma-separated)"
    password: false
  - name: CHATTO_ROOM_TOOLSETS
    description: "Per-room toolset restriction as comma-separated room_id:toolset entries, e.g. RbmwiHk4vs9a3Ql:web,RbmwiHk4vs9a3Ql:file — several entries for one room accumulate. A room with an entry REPLACES the platform's toolset list for its turns, so list every toolset the room should keep; rooms without an entry keep the normal platform toolsets. (default: none — no room is restricted)"
    prompt: "Per-room toolsets (room_id:toolset, comma-separated)"
    password: false
  - name: CHATTO_REACTIONS
    description: "Add 👀/✅/❌/🚫 reactions to messages during processing (default: true)"
    prompt: "Enable message reactions? (true/false)"
    password: false
  - name: CHATTO_EDIT_DISPATCH
    description: "Treat edits of chat messages as corrections: a message being processed is restarted with the edited text, a message the bot ignored (e.g. missing @mention) is re-checked against its new text. Already-answered messages stay answered, and edits older than CHATTO_EDIT_WINDOW are ignored. (default: true)"
    prompt: "Process message edits as corrections? (true/false)"
    password: false
  - name: CHATTO_EDIT_WINDOW
    description: "How long after posting an edit may still land, in seconds; older edits are ignored (default: 300)"
    prompt: "Edit window in seconds (or empty for 300)"
    password: false
  - name: CHATTO_RESUME_WINDOW
    description: "How long a stream position saved by a clean shutdown may still be used after a gateway restart, in seconds. Within the window the bot receives what arrived while it was down; an older position is discarded so a long outage does not replay hours of history. 0 disables it, and a crash (no clean shutdown) leaves no position to resume from. (default: 900)"
    prompt: "Restart resume window in seconds (or empty for 900, 0 disables)"
    password: false