Set Up Hermes Agent on Telegram: Your 24/7 AI Assistant

Why Connect Hermes to Telegram?

The CLI is powerful, but you're not always at your terminal. With Telegram integration, Hermes becomes a personal AI assistant in your pocket:

• 24/7 access — Chat with Hermes from your phone, tablet, or any device
• Push notifications — Get alerts from cron jobs and monitoring tasks
• Media support — Send images, documents, and voice messages for analysis
• Group mode — Add Hermes to team channels for collaborative AI
• Persistent sessions — Your Telegram conversations sync with CLI sessions

Prerequisites

Before you start, make sure you have:

• Hermes Agent installed and configured
• A Telegram account
• A working AI model configured
• A VPS or always-on machine to run Hermes (for 24/7 availability)

Step 1: Create a Telegram Bot

Get Your Bot Token from BotFather

Open Telegram and search for @BotFather

Send /newbot

Choose a display name for your bot (e.g., "My Hermes AI")

Choose a username (must end in bot, e.g., my_hermes_ai_bot)

BotFather will give you an API token:

Done! Your bot was created successfully.
Use this token to access the HTTP API:
7123456789:AAH1234567890abcDefGhIjKlMnOpQrStUvW

Important: Keep this token secret! Anyone with the token can control your bot.

Configure Bot Settings with BotFather

Send these commands to @BotFather:

/setdescription
Select your bot → "Your personal AI assistant powered by Hermes Agent"

/setabouttext
Select your bot → "I can help with code, files, web search, and much more. Powered by Hermes Agent."

/setcommands
Select your bot → paste the following:
help - Show available commands
model - Switch AI model
session - Manage conversation sessions
clear - Clear conversation history
memory - Manage long-term memory
status - Show current status

Step 2: Configure Hermes

Set the Bot Token

hermes config set telegram.bot_token "7123456789:AAH1234567890abcDefGhIjKlMnOpQrStUvW"
hermes config set telegram.enabled true

Restrict Access (Important!)

By default, anyone who finds your bot can talk to it (and use your API credits). Always restrict access to your Telegram user ID:

Find your Telegram user ID — send /start to @userinfobot

Set allowed users:

hermes config set telegram.allowed_users "[123456789]"

For multiple users:

hermes config set telegram.allowed_users "[123456789, 987654321]"

Complete Telegram Configuration

# ~/.hermes/config.yaml
telegram:
  enabled: true
  bot_token: "7123456789:AAH..."
  allowed_users: [123456789]

  # Optional settings
  parse_mode: "Markdown"        # Message formatting
  max_message_length: 4096      # Telegram's message limit
  split_long_messages: true     # Auto-split long responses
  send_typing_indicator: true   # Show "typing..." while processing
  webhook_mode: false           # Use polling (simpler setup)

  # File handling
  allow_file_upload: true       # Accept file attachments
  max_file_size: 20             # Max file size in MB
  download_dir: "~/hermes-telegram-files"

Step 3: Start the Telegram Bot

Foreground Mode (for testing)

hermes telegram start

🤖 Telegram bot started!
 Bot: @my_hermes_ai_bot
 Mode: Polling
 Allowed users: [123456789]
 Model: anthropic/claude-3.5-sonnet

Waiting for messages...

Background Mode (for production)

Use nohup or a process manager:

# Simple background
nohup hermes telegram start > ~/hermes-telegram.log 2>&1 &

# Using PM2 (recommended)
pm2 start "hermes telegram start" --name hermes-telegram
pm2 save
pm2 startup  # Auto-start on system boot

Using systemd (Linux)

Create a service file:

sudo tee /etc/systemd/system/hermes-telegram.service << 'EOF'
[Unit]
Description=Hermes Agent Telegram Bot
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/local/bin/hermes telegram start
Restart=always
RestartSec=10
Environment="HERMES_API_KEY=sk-or-v1-your-key"

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable hermes-telegram
sudo systemctl start hermes-telegram

Check the status:

sudo systemctl status hermes-telegram

Step 4: Using Hermes on Telegram

Basic Conversation

Just send messages naturally:

You: How do I reverse a linked list in Python?

Hermes: Here's an efficient implementation:

def reverse_linked_list(head):
    prev = None
    current = head
    while current:
        next_node = current.next
        current.next = prev
        prev = current
        current = next_node
    return prev

This iterates through the list once (O(n) time, O(1) space)...

Bot Commands

| Command | Description |

|---------|-------------|

| /help | Show available commands |

| /model fast | Switch to a faster model |

| /model smart | Switch to a smarter model |

| /session new project-x | Create a new session |

| /session list | List all sessions |

| /clear | Clear conversation history |

| /status | Show current model, session, and stats |

Sending Files

Send any file to Hermes for analysis:

• Code files — "Review this code and suggest improvements"
• Log files — "Summarize the errors in this log"
• Documents — "Summarize this PDF in 3 bullet points"
• Images — "Describe what's in this image" (requires multimodal model)

Voice Messages

Send a voice message and Hermes will transcribe and respond:

🎤 Voice message received (15 seconds)
📝 Transcription: "Can you help me write a Docker compose file for
   a Node.js app with PostgreSQL and Redis?"

Sure! Here's a docker-compose.yml for your stack...

Step 5: Advanced Features

Group Chat Mode

Add Hermes to a group chat for team collaboration:

Add your bot to a Telegram group

Make it an admin (so it can read messages)

Configure group settings:

telegram:
  group_mode:
    enabled: true
    trigger_prefix: "/ai"     # Only respond when message starts with /ai
    allowed_groups: [-1001234567890]  # Group chat IDs

In the group, users would type:

/ai Write a SQL query to find duplicate emails

Webhook Mode (Advanced)

For better performance, use webhooks instead of polling:

telegram:
  webhook_mode: true
  webhook_url: "https://your-server.com/api/telegram"
  webhook_port: 8443

Inline Mode

Enable inline queries to use Hermes from any chat:

@my_hermes_ai_bot convert 100 USD to EUR

Security Checklist

Before going live, verify:

• [ ] allowed_users is set (prevents unauthorized access)
• [ ] Bot token is stored securely (not in git)
• [ ] File upload limits are set
• [ ] Rate limiting is configured
• [ ] Hermes file system access is restricted (see config guide)

Troubleshooting

Bot not responding

# Check if the process is running
pm2 status hermes-telegram

# Check the logs
pm2 logs hermes-telegram --lines 50

# Test the connection manually
hermes telegram test

"Unauthorized" errors

Your Telegram user ID might be wrong. Verify it:

Send /start to @userinfobot to get your correct ID

Long messages getting cut off

Telegram has a 4096-character limit per message. Enable message splitting:

telegram:
  split_long_messages: true
  max_message_length: 4096

Next Steps

Your Hermes Telegram bot is live! Explore more:

• Discord integration — Add Hermes to your Discord server
• Multi-platform gateway — Connect all messaging platforms at once
• Cron scheduling — Get automated reports via Telegram

---

Last updated: April 16, 2026 · Hermes Agent v0.8