← All connection guides

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 setup

3. 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 gateway

Practice

4. Verify a private conversation

  1. 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