Connect Hermes Agent to Telegram

Step 1: Create a Telegram bot

Open Telegram and search for @BotFather — Telegram's official bot management tool. Start a chat and send:

/newbot

BotFather will ask for a name and a username (must end in bot, e.g., HermesAssistantBot). Once created, BotFather gives you an API token — a long string like:

1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567890

Save this token securely. Anyone with it can control your bot. Treat it like a password.

Step 2: Configure the Telegram gateway

Open your Hermes configuration file at ~/.hermes/config.yaml and add or update the gateway section:

gateway:
  telegram:
    enabled: true
    token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567890"
    # Optional: restrict to specific users by Telegram user ID
    # allowed_users:
    #   - 123456789

For production use, store the token in ~/.hermes/.env and reference it via environment variable instead of hardcoding:

gateway:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}

Then add to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567890

Step 3: Start the gateway

With your configuration in place, start the Hermes gateway service:

hermes gateway start

You should see output confirming the Telegram gateway is connected and listening. The gateway runs as a background process that bridges Telegram messages to your Hermes Agent.

To keep it running persistently, consider running it under launchd (macOS) or systemd (Linux).

Step 4: Test your bot

Open Telegram and find your bot by its username (the one you registered with BotFather). Send a message to start a conversation:

/help

Your Hermes Agent should respond with a help message listing available commands and capabilities. Try a real prompt:

What's on my calendar today?

If the bot doesn't respond, check:

• The gateway is running — hermes gateway status
• The token is correct in your config
• Your firewall allows outbound HTTPS to api.telegram.org
• Check gateway logs: hermes gateway logs

Security and access control

By default, anyone who finds your bot's username can message it. To restrict access:

• Allowed users: Add allowed_users with your Telegram user ID in config.yaml. Your user ID can be found by messaging @userinfobot on Telegram.
• Command whitelist: Restrict which Hermes capabilities are available over Telegram (e.g., read-only tools vs. write access).
• Rate limiting: The gateway includes basic rate limiting to prevent abuse.

Privacy considerations

Telegram is a cloud-based messaging platform. Keep these points in mind:

• Messages transit Telegram's servers: Your prompts and Hermes' responses pass through Telegram's infrastructure. Telegram uses encrypted transport (MTProto), but messages are stored on their servers for sync across your devices.
• Bot messages are not end-to-end encrypted: Unlike Telegram "Secret Chats," bot conversations use standard server-side encryption. The bot token grants access to all messages sent to the bot.
• Data residency: Telegram's servers are distributed globally. For Canadian organizations handling personal information under PIPEDA, consider whether cloud-based messaging fits your data handling requirements.
• Recommendation: Avoid sending sensitive personal information, credentials, or regulated data through the Telegram gateway. Use the local CLI for sensitive workflows.