🤖 Multi-User Telegram Setup Guide

How to run 4 distinct Telegram channels for 4 different users on a single Hermes Agent instance

📑 Table of Contents

Overview
Prerequisites
How Multi-User Works
Step 1: Create Telegram Bot
Step 2: Configure Environment Variables
Step 3: Get User Chat IDs
Step 4: Configure Allowed Users
Step 5: Start the Gateway
Step 6: Verify Each User
Advanced Options
Troubleshooting

📋 Overview

Hermes Agent's Telegram gateway has built-in multi-user support. Each Telegram user gets their own isolated session, meaning:

✅ User Isolation — Each user's conversation history is separate
✅ No Cross-Talk — User A won't see User B's messages
✅ Single Bot — One bot handles all 4 users via DMs
✅ Session Persistence — Each user's session resumes separately

💡 Key Insight: You don't need 4 separate bots. One Telegram bot can handle unlimited users via direct messages. Each user's chat_id creates a unique session.

📦 Prerequisites

Requirement	Status	Notes
Hermes Agent installed	Required	Already running on your VM
Telegram Bot Token	Required	From @BotFather
4 Telegram user accounts	Required	Users who will DM the bot
Network access	Optional	For webhook mode

🏗️ How Multi-User Works

📱 User 1 sends DM to @YourBot

↓

🔐 Telegram delivers user_id + chat_id

↓

🔑 Hermes checks TELEGRAM_ALLOWED_USERS

↓

📂 Creates session: telegram:chat_id_1

↓

🤖 Processes message in isolated session

Each user gets their own session key in format: telegram:CHAT_ID

Step 1: Create Telegram Bot

Open Telegram and start @BotFather

Search for @BotFather in Telegram and start a chat with it.

Create a new bot

Send the command:

/newbot

Follow the prompts to name your bot. You'll receive a bot token like:

1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Set bot commands (optional)

For better UX, set the bot commands menu:

/setcommands

Paste this command list:

new - Start a fresh session
reset - Clear and start fresh
model - Show/change AI model
skills - Manage skills
status - Show connection status

✅ Save your bot token: YOUR_BOT_TOKEN_HERE

Step 2: Configure Environment Variables

Add these variables to your ~/.hermes/.env file:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_USERS=

ℹ️ Note: Leave TELEGRAM_ALLOWED_USERS empty for now. We'll add user IDs after Step 3.

Step 3: Get User Chat IDs

To find each user's Telegram chat_id, you need to either:

Option A: Use a Chat ID Bot (Recommended)

Search for @userinfobot

Start a chat with @userinfobot on Telegram.

Get the chat_id

The bot will reply with user information including the ID. This is the user's chat_id.

Example response:

ID: 123456789
First Name: John
Last Name: Doe
Username: johndoe

Option B: Check Gateway Logs

Temporarily allow all users

Set in ~/.hermes/.env:

TELEGRAM_ALLOWED_USERS=*

Start gateway and check logs

cd ~/.hermes/hermes-agent
source venv/bin/activate
python -m gateway.run &

When users message the bot, their chat_id appears in ~/.hermes/logs/gateway.log

⚠️ Security: Option B exposes your bot to all users. Remove the * after getting chat_ids.

Step 4: Configure Allowed Users

Now add the 4 user chat_ids to your environment:

Edit ~/.hermes/.env

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555,111111111

Separate multiple user IDs with commas. No spaces!

User #	Chat ID	Purpose
User 1	`123456789`	Primary user (Thota)
User 2	`987654321`	Secondary user
User 3	`555555555`	Third user
User 4	`111111111`	Fourth user

Step 5: Start the Gateway

Restart the gateway

hermes gateway restart

Or if running manually:

cd ~/.hermes/hermes-agent
source venv/bin/activate
python -m gateway.run

Verify startup

Check the gateway log:

tail -20 ~/.hermes/logs/gateway.log

Look for:

[Telegram] Bot connected successfully
[Telegram] Listening for messages...

Step 6: Verify Each User

Now test with each user:

User 1 DMs the bot

Have User 1 open a chat with @YourBot and send:

/status

They should get a response confirming their user ID.

User 2 DMs the bot

User 2 sends a message — should get a fresh session, not User 1's history.

Repeat for Users 3 & 4

Each user should have isolated sessions.

✅ Success! You now have 4 users with isolated Telegram sessions on a single Hermes Agent.

🔧 Advanced Options

Per-User Configuration

You can give each user different settings by using session profiles:

# In config.yaml
sessions:
  profiles:
    user_123456789:
      model: anthropic/claude-sonnet-4
      toolsets: [terminal, file, web]
    user_987654321:
      model: openai/gpt-4o
      toolsets: [terminal, file]

Custom Welcome Messages

Use the /boot feature to send custom welcomes per user:

# ~/.hermes/gateway/builtin_hooks/welcome.md
# This message sent on first contact

{% if user_id == "123456789" %}
👋 Welcome to your personal AI assistant, Thota!
{% elif user_id == "987654321" %}
👋 Hello! How can I help you today?
{% endif %}

Memory Isolation

Ensure each user's memory is isolated by using the default session-based storage. It automatically separates by chat_id.

🔍 Troubleshooting

Problem	Solution
"Not authorized"	Add user ID to TELEGRAM_ALLOWED_USERS
Messages not arriving	Check allowed_updates in config or restart gateway
Session mixup	Use /new to start fresh session
Bot offline	Run `hermes gateway restart`

Common Commands

# List sessions
hermes sessions list

# Delete a specific session
hermes sessions delete SESSION_ID

# Show gateway status
hermes gateway status

# View live logs
tail -f ~/.hermes/logs/gateway.log