Hermes Agent HelperHermes Agent Helper

Complete Telegram Setup Guide: Connect Hermes Agent to Telegram Bot

Hermes Agent Helperon a month ago

Overview

Telegram is a globally popular instant messaging app known for its security and open Bot API. Hermes Agent supports conversational interactions with users through Telegram Bots. This tutorial will guide you through the complete process from creating a Bot to configuring the Hermes Gateway.

Estimated setup time: 5-10 minutes

Required information:

  • Bot Token (obtained from BotFather)
  • Your Telegram User ID (for access authorization)

Step 1: Create a Telegram Bot

1.1 Find BotFather

BotFather is Telegram's official Bot management tool. All Bot creation is done through it.

  1. Open the Telegram app
  2. Search for @BotFather in the search box
  3. Click to enter the conversation with BotFather

Tip: Make sure to select the official BotFather with the blue verification badge.

1.2 Create a New Bot

  1. In the BotFather conversation, send:

    /newbot

  2. BotFather will ask for your Bot's display name:

    • This is the display name, can include any characters
    • Example: Hermes AI Assistant

  3. Next, enter the Bot's username:

    • Must end with bot
    • Can only use letters, numbers, and underscores
    • Example: my_hermes_ai_bot

1.3 Get Bot Token

After successful creation, BotFather will return a message containing your Bot Token:

Done! Congratulations on your new bot. You will find it at t.me/my_hermes_ai_bot.

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Save this Token securely - it's the only credential for accessing the Bot API.

⚠️ Security Reminder:

  • Don't share the Token with others
  • Don't commit the Token to public code repositories
  • If the Token is leaked, immediately regenerate it using the /revoke command via BotFather

Step 2: Get Your Telegram User ID

The Telegram User ID is used to authorize which users can chat with the Bot.

  1. Search for @userinfobot in Telegram
  2. Click "Start" or send any message
  3. The bot will reply with your user info, including the Id field

Example:

@your_username
Id: 123456789

Here, 123456789 is your User ID.

Method 2: Using @getmyid_bot

  1. Search for @getmyid_bot in Telegram
  2. Click "Start"
  3. The bot will directly return your User ID

Method 3: Check Gateway Logs

  1. Complete the configuration below and start the Gateway (temporarily allow all users)
  2. Send a test message to your Bot
  3. Check the Gateway logs for the sender's User ID

Step 3: Configure Hermes Gateway

If you're using our managed service:

  1. Go to the Hermes Service Manager page
  2. Log in to your server management interface
  3. Use the "Telegram Setup" quick configuration tab:
    • Enter Bot Token
    • Click "Complete Setup"
  4. The system will automatically write the configuration and restart the Gateway

Or manually configure in the "Config" tab:

  • gateway.telegram.bot_token: Your Bot Token
  • gateway.telegram.allowed_users: Authorized user IDs (comma-separated)

Option 2: Via Interactive Wizard

Run in your server terminal:

hermes gateway setup

Follow the prompts:

  1. Select "Telegram"
  2. Enter Bot Token
  3. Enter allowed user IDs (comma-separated)

Option 3: Manual Configuration

Edit the ~/.hermes/.env file and add:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_ALLOWED_USERS=123456789,987654321

Environment Variables:

  • TELEGRAM_BOT_TOKEN: Required, Token obtained from BotFather
  • TELEGRAM_ALLOWED_USERS: Optional, list of allowed user IDs, comma-separated
  • If TELEGRAM_ALLOWED_USERS is not set, you need to set GATEWAY_ALLOW_ALL_USERS=true (not recommended for production)

Step 4: Start and Test

4.1 Start the Gateway

Run in foreground (for testing):

hermes gateway run

Or start as a system service:

hermes gateway install
hermes gateway start

4.2 Test the Bot

  1. Find your Bot in Telegram (via the link returned by BotFather)
  2. Click "Start" or send /start
  3. Send a test message like "Hello"
  4. If configured correctly, the Bot will reply with an AI-generated response

Optional Configuration

Set Bot Description and Avatar

You can further customize your Bot through BotFather:

  1. Send /mybots to view all your Bots
  2. Select the Bot to edit
  3. Available options:
    • Edit Bot → Edit Description: Set Bot description
    • Edit Bot → Edit About Text: Set about text
    • Edit Bot → Edit Botpic: Set Bot avatar

Set Command Menu

  1. Select your Bot in BotFather
  2. Choose Edit Bot → Edit Commands
  3. Add commands in the format: 
    start - Start conversation
help - Get help
clear - Clear conversation history

Troubleshooting

Q: Bot doesn't respond to messages

Possible causes:

  1. Gateway not running
  2. Incorrect Bot Token
  3. User ID not in allowed list

Solutions:

  1. Check Gateway status: hermes gateway status
  2. Verify Token is correct
  3. Check TELEGRAM_ALLOWED_USERS configuration

Q: Received "Unauthorized" error

Cause: Bot Token is invalid or has been revoked

Solutions:

  1. Check if Token is valid via BotFather
  2. If needed, regenerate Token using /revoke
  3. Update the Token in configuration file

Q: High message latency

Possible causes:

  1. Unstable server network
  2. Slow LLM API response

Solutions:

  1. Check network connection from server to Telegram servers
  2. Consider using a faster LLM model
  3. Check response times in Gateway logs

Q: How to allow group use of Bot

By default, the Bot only responds to private messages. To use in groups:

  1. Set via BotFather: /setprivacy → Select Bot → Disable
  2. Add group ID (negative number) to the allowed list in configuration

For questions, please contact us for technical support.