Sókrates Wiki

Hermes Slack Integration

2 min read

Hermes Slack Integration

Summary

Hermes supports Slack as a communication channel using Slack’s Socket Mode, which allows the agent to receive events without requiring a public webhook URL. This is critical for the Sokrates project as it enables the agent to run on-premises within the sokrates-box (NixOS appliance) behind restrictive firewalls.

Details

The Slack integration for Hermes is designed to mirror the functionality of its Discord integration, utilizing a similar configuration pattern within the NixOS module system.

Configuration and Deployment

The integration is managed via the hermes.nix configuration file. Key configuration parameters include:

  • free_response_channels: A list of Slack channel IDs (e.g., C0AQ2A02SRM) where the bot will respond to all messages without requiring a mention.
  • require_mention: A boolean (typically set to true for general channels) that dictates whether the bot must be explicitly tagged to trigger a response.

Secrets are managed idempotently and injected into the environment at /var/lib/sokrates/secrets/hermes/hermes.env. The integration requires two specific tokens:

  1. Bot User OAuth Token (`xoxb-…): Scoped to the workspace, used for sending messages and reading history.
  2. **App-Level Token (xapp-...)**: Requires the connections:write` scope to enable Socket Mode communication.

Slack App Manifest

To ensure consistent setup, Hermes is deployed using a standardized Slack App Manifest. The manifest defines the following requirements:

  • Features: Socket Mode must be enabled. The “Messages Tab” in the App Home must be active to allow direct messaging.
  • Bot Scopes: chat:write, channels:history, channels:read, groups:history, groups:read, im:history, im:read, im:write, reactions:write, files:read, files:write, and users:read.
  • Events: The bot subscribes to message.channels, message.groups, and message.im.

Operational Requirements

For Hermes to function correctly within a Slack workspace:

  • Channel Invitation: Unlike some other platforms, Slack bots cannot see messages in channels they have not joined. Users must manually invite the bot using the /invite @Hermes command.
  • App Home Settings: For DM (Direct Message) support, the “Allow users to send Slash commands and messages from the messages tab” setting must be enabled in the Slack API dashboard.
  • Connectivity: Hermes establishes a WebSocket connection to Slack (often routed via Cloudflare’s edge) to maintain the Socket Mode session.

Graph View

Backlinks