All plugins

chatto-platform

Chatto gateway adapter for Hermes Agent. Connects to a Chatto server (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 eve

jrimmer4PlatformUpdated 1 month ago

About

Chatto gateway adapter for Hermes Agent. Connects to a Chatto server (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 eve

Hermes Chatto Plugin

A Chatto platform adapter plugin for Hermes Agent. Connects your self-hosted Chatto server to Hermes so you can interact with the agent through chat rooms and DMs.

Install

hermes plugins install jrimmer/hermes-chatto-plugin

Or with the full URL:

hermes plugins install https://github.com/jrimmer/hermes-chatto-plugin.git

Then add your Chatto credentials to ~/.hermes/.env:

CHATTO_URL=https://chat.example.com
CHATTO_LOGIN=max
CHATTO_PASSWORD=your-password
CHATTO_HOME_CHANNEL=REljMv5Pgolo6Y9

Enable the plugin (if not auto-enabled during install):

hermes plugins enable chatto-platform

Restart the gateway:

hermes gateway restart

Configuration

Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| CHATTO_URL | Yes | Base URL of your Chatto server |
| CHATTO_LOGIN | Yes | Chatto username |
| CHATTO_PASSWORD | Yes | Chatto password |
| CHATTO_HOME_CHANNEL | No | Room ID for cron/notification delivery (defaults to first watched room) |
| CHATTO_CHANNELS | No | Comma-separated room IDs to watch (default: all joined rooms) |
| CHATTO_REQUIRE_MENTION | No | Only respond to @mentions in rooms (default: true). DMs always respond. |
| CHATTO_AUTO_THREAD | No | Auto-create threads for replies in rooms (default: true) |
| CHATTO_FREE_RESPONSE_CHANNELS | No | Comma-separated room IDs where bot responds without being tagged |
| CHATTO_ALLOWED_USERS | No | Comma-separated Chatto logins allowed to talk to the bot |
| CHATTO_ALLOW_ALL_USERS | No | Allow any Chatto user to talk to the bot (true/false) |

YAML Config (optional)

You can also configure via ~/.hermes/config.yaml instead of env vars:

gateway:
  platforms:
    chatto:
      enabled: true
      extra:
        url: https://chat.example.com
        require_mention: true
        home_channel: REljMv5Pgolo6Y9
        free_response_channels: []

Features

  • WebSocket realtime — binary protobuf codec for Chatto's realtime protocol (no protobuf library needed)
  • ConnectRPC REST API — JSON over HTTP for outbound messages, room discovery, user lookup
  • Thread support — GetThreadEvents for thread replies, auto-thread creation, proper threadRootEventId handling
  • DM support — DMs always get a response, no threading in DM rooms
  • Mention filtering — require_mention (default true) with free_response_channels for no-tag rooms
  • Dynamic room discovery — auto-joins new rooms without gateway restart (watches room_created / user_joined_room events)
  • Event handling — message_posted, mention_notification, new_dm_notification, session_terminated (force reconnect), message_retracted, user_left_room
  • Presence broadcasting — periodic presence refresh
  • Standalone cron delivery — works outside the gateway process

How It Works

The adapter connects to Chatto via two channels:

  1. WebSocket (/api/realtime) — receives realtime events as binary protobuf frames
  2. ConnectRPC REST (/api/connect/) — sends messages, fetches room events, joins rooms, manages presence

When a message is received, the WebSocket frame is decoded, the message body is fetched via REST, dispatched to the Hermes agent, and the response is sent back via CreateMessage with proper threading.

Tested Against

Chatto v0.4.19. Protocol version 1 (binary protobuf over WebSocket).

License

MIT

README from the reviewed commit aab0a20; it updates when the author re-pins.