How to connect Hermes Agent to Telegram
Connect Hermes Agent to Telegram through its messaging gateway and verify an authorized private message round trip.
Free guide · Updated
Based on official documentation · Checked
Ask your agent
Copy the prompt and paste it into your assistant.
Quick answer
Hermes Agent connects to Telegram as a bot through its messaging gateway. Telegram is the conversation surface; the gateway runs on your host and uses your configured model provider. This is a native messaging integration rather than an MCP server connection.
Before you start
Use a separate test bot and Hermes profile on a host you control. Confirm ordinary Hermes chat already works with its model provider. Keep existing production gateways running as configured. A valid Telegram token alone cannot prove that inference and reply delivery work.
1. Create the bot
In Telegram, open the official @BotFather account and issue /newbot. Choose a unique bot username ending in bot. Store the issued token privately. Your human Telegram user ID is different from the bot ID and from a group chat ID; do not substitute one for another.
2. Configure the selected Hermes profile
Run the interactive gateway setup for the profile intended for this test, select Telegram, and provide the bot token and allowed human user IDs in the local setup flow. The default-profile command below affects the default profile, so do not use it against an existing production setup.
hermes gateway setup3. Start the matching gateway
The official guide documents the gateway command below. Run it only for the prepared test profile. Track the process you start. Check the host, profile and token selection if the bot is configured but silent; do not repeatedly rotate tokens without diagnosing the path.
hermes gatewayPractice
4. Verify a private conversation
- From the allowed human account, send a new neutral message to the test bot asking it to return a short phrase unique to this test. Check that the reply arrives in the intended private chat.
Output: A complete receipt → authorization → model response → Telegram delivery round trip, with no private message text in public evidence.
5. Check authorization and restart
Confirm only the intended accounts are allowed. In a dedicated test environment, restart only the gateway you own and send a new test message. Do not infer success from a stored token, an enabled platform or a reply left over from a previous run.
Troubleshooting
No reply: inspect the selected profile, running gateway and message receipt. Unauthorized response: check the human sender ID and allowlist. Model error after receipt: fix the provider configuration rather than the Telegram token. Test DM behavior before attempting group privacy and mention settings.
Disconnect and limits
Stop the test gateway process, disable its Telegram configuration and revoke the test bot token through BotFather if no longer needed. Keep production profile credentials intact. Set up a private text conversation first; group chats, voice and attachments have additional configuration requirements.
Sources
Read the primary material
- Hermes TelegramNous Research / Hermes Agent