Telegram Setup

Telegram is the most common gateway platform for Hermes, and for good reason: bot registration takes under a minute, the Bot API is well-documented, and the platform handles long messages, voice notes, and file attachments natively. You can go from zero to a working agent on your phone in about five minutes.

This lesson covers the full setup: registering a bot with @BotFather, connecting it to the Hermes gateway, configuring DM topic sessions and home channel, and handling the message length limits that catch everyone the first time.

What you'll learn

• Bot registration is a single conversation with @BotFather on Telegram, you get an API token that's the only credential Hermes needs
• hermes gateway setup walks through the token entry and tests the connection before saving anything
• /sethome pins a chat as the default delivery channel; DM topic sessions (/topic on) keep multi-subject conversations organized
• Telegram has a 4,096-character message limit, responses longer than this are split into multiple messages automatically, but long code blocks or tables can break across splits

The problem

You have a gateway service running (from the previous lesson), but it's not connected to anything. You need to register a platform integration, configure the gateway to use it, and verify that Hermes is reachable from outside your terminal. Telegram is the fastest path from zero to working because it has the fewest setup steps and no permission model to configure.

Options & when to use each

Approach	What it does	Costs you	When to pick it
Single bot, personal use	One bot token, one Hermes instance, you're the only user	Five minutes of setup	Most people, most of the time. This is what the lesson covers
Single bot, multi-user	Same bot, but you invite others to chat with it	You need to configure pairing approval (hermes pairing approve) for each new user	Small team where everyone should have equal access
Multiple bots, one gateway	Different bot tokens for different purposes (work vs. personal)	Each bot needs its own @BotFather registration and token	You want different Hermes profiles or tool configurations for different contexts
Group chat bot	Bot added to a Telegram group, responds to messages there	Group chat context is shared, everyone sees Hermes's responses	Team channels, monitoring alerts, shared project context

This lesson covers the single-bot personal setup. The multi-platform lesson covers running multiple platforms side by side.

Build it

Step 1: Register a bot with @BotFather

Open Telegram and search for @BotFather , this is Telegram's official bot management account. Start a conversation and send:

/newbot

@BotFather will ask for a name (this is the display name, can be anything) and a username (must end in bot, like my_hermes_bot). After you provide both, it returns an API token that looks like:

110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Copy this token. You'll need it in the next step, and there's no way to retrieve it later without generating a new one (use /revoke with @BotFather if you lose it).

Step 2: Connect the bot to the gateway

Launch the setup wizard to connect your Telegram bot to Hermes. The wizard prompts for your token and validates it against the Telegram API.

hermes gateway setup

This opens the interactive gateway configuration wizard. Select Telegram from the platform list and paste the bot token when prompted. The wizard tests the connection before saving, if the token is wrong or the bot isn't registered, it tells you immediately and doesn't write anything to config.

If you prefer to configure Telegram directly without the wizard:

hermes gateway setup telegram

This skips the platform selection and goes straight to the Telegram token prompt.

Step 3: Restart the gateway

Platform configuration changes require a gateway restart:

hermes gateway restart

Check the logs to confirm Telegram connected:

grep -i telegram ~/.hermes/logs/gateway.log | tail -5

You should see a line confirming the Telegram adapter initialized successfully. If you see an authentication error instead, the token is wrong, go back to @BotFather and use /mybots to check or regenerate it.

Step 4: Send your first message

Open Telegram, find your bot by its username, and send a message. Anything works , "hello" is fine for the first test. Hermes processes it through the same agent core you've been using from the terminal, with the same model, the same skills, and the same tool access (except what you've explicitly disabled for the gateway).

The first response may take a few seconds longer than subsequent ones, the gateway is initializing the conversation session. After that, responses should arrive at the same speed you're used to from the CLI.

Step 5: Set your home channel

The home channel is where Hermes sends unprompted messages, cron job results, long-running task completions, scheduled summaries. Set it with the /sethome slash command sent to your bot:

/sethome

Send this from the chat where you want notifications to land. Hermes confirms with a message. From now on, any automated delivery from the gateway targets this chat.

You can change it at any time by sending /sethome from a different chat.

Step 6: Enable DM topic sessions (optional)

When you have multiple threads of conversation going with Hermes, a coding task, a research thread, a system monitoring check, it's useful to keep them in separate topics rather than one long scroll. Telegram DM topic sessions create virtual threads inside your bot conversation:

/topic on

After enabling topics, each new message starts a fresh topic. Use /topic new to manually create one, /topic list to see all active topics, and /topic off to return to a single thread.

Topics are session-level, not persistent across restarts. They're for organizing a long work session, not for permanent categorization.

What goes wrong

Mistake	How you notice it	The fix
Bot doesn't respond to messages	You send a message, nothing happens, no error	Check the gateway log: grep telegram ~/.hermes/logs/gateway.log. If the adapter never initialized, the token is wrong or the bot isn't registered. If it initialized but messages don't arrive, the gateway might not be running: hermes gateway status
"Bot token invalid" during setup	The wizard rejects the token immediately	You pasted the wrong value or the token was revoked. Go to @BotFather, use /mybots → select your bot → API Token → generate a new one. Delete the old token, it won't work anymore
Long responses arrive in broken fragments	Hermes sends a long code block, but it's split across messages with the code fence broken in the middle	Telegram's 4,096-character limit is per-message. Code blocks, tables, and formatted text break when split across messages. Hermes splits automatically, but complex formatting doesn't survive the split. For long code output, ask Hermes to send it as a file instead
Bot responds to everyone who finds it	Strangers are sending messages and Hermes is responding	Configure pairing approval: hermes pairing approve or set the gateway to require explicit approval for new users. By default, Hermes responds to anyone who messages the bot, the pairing system gates access per-user
/sethome doesn't work	Hermes replies with an error or doesn't acknowledge	This is a gateway-only slash command, it doesn't work from the CLI. Make sure you're sending it as a Telegram message to the bot, not from a terminal session

Confirm it worked

Verify the configuration by checking the gateway status and sending a real task through Telegram. Ensure that the integration works end to end.

# 1. Verify the gateway is running and Telegram is connected
hermes gateway status
grep -i "telegram.*started\|telegram.*initialized" ~/.hermes/logs/gateway.log

# 2. Send a real task from Telegram, not a hello-world
# In Telegram, message your bot:
# "What's the current disk usage on the machine you're running on?
#  Show the top 3 directories by size."

# 3. Verify Hermes used tools (the response should include actual
#    filesystem data, not a generic answer)

# 4. Test /sethome from Telegram
# Send: /sethome
# Hermes should confirm the home channel is set

# 5. Check that gateway slash commands work
# Send: /platforms
# Hermes should list connected platforms with status

If step 2 returns actual disk usage data from your machine, the gateway is working end to end: Telegram → gateway → agent core → tool execution → response → Telegram. You're now controlling your agent from your phone.

Next: Discord Setup , connect Hermes to your Discord server with slash commands, channel permissions, and voice channel support.