How to connect Telegram Bot to Hermes Agent
Connect Telegram Bot to Hermes with ClawLink: paste your Telegram Bot key once and 18 tools work from chat. No MCP server to run, nothing stored on your machine.
Telegram BotAPI KEYMCPAutomate Telegram chats and channels through a Telegram Bot. Requires a bot token from @BotFather.. Once connected, Hermes Agent can read and act on Telegram Bot from chat — pairing, token refresh, and tool wiring handled for you.
Most guides for giving Hermes Agent Telegram Bot access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Telegram Bot setup: pair once in the browser and your always-on Hermes agent can act on Telegram Bot for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.
Copy this prompt into Hermes to install the plugin and pair your account.
Set up ClawLink for Hermes and tell me when it's ready.
1. Install the plugin:
hermes plugins install ClawLink-HQ/hermes-plugin --enable
2. Start pairing. It prints an approval link, so show me the link and stop, don't wait:
hermes clawlink begin
3. I'll approve it in my browser, then reply "approved".
4. When I say approved, finish setup:
hermes clawlink finish
5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.Setup
It takes three steps to connect Hermes to Telegram Bot.
1Install and pair
Install the ClawLink plugin, then pair Hermes with a one-time browser approval:
hermes plugins install ClawLink-HQ/hermes-plugin --enable- 2
Connect Telegram Bot
Paste your API key in the dashboard.
- 3
Use it from chat
Ask Hermes Agent: "What can you do with Telegram Bot?"
Install by command
The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin # prints an approval link — open it and approve
hermes clawlink finish # after approving in the browser
hermes clawlink testThen connect Telegram Bot in the ClawLink dashboard — paste your Telegram Bot API key once.
Verify the connection by asking Hermes:
Use telegram_get_chat to confirm the bot can see the chat I name, then telegram_send_message the text I paste to it. Confirm the message id before you finish.
Using a different agent?
The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:
npx -y @useclawlink/cli loginlogin opens the same browser approval and stores a credential locally. Once Telegram Bot is connected in the dashboard, that agent calls the same 18 Telegram Bot tools over MCP. Full setup for MCP clients and shell agents: connect apps to any AI agent.
Telegram Bot MCP for Hermes
Looking for a Telegram Bot MCP server for Hermes Agent? ClawLink connects Telegram Bot to Hermes Agent and exposes 18 Telegram Bot tools your agent can call over MCP, with hosted auth and nothing to run or maintain yourself. Using OpenClaw instead? The OpenClaw Telegram Bot integration works the same way.
The AI Overview's answer for "connect Telegram to Hermes" is a full BotFather walkthrough: message @BotFather, run /newbot, copy the token, ask @userinfobot for your numeric user ID, put both in env vars, start the gateway, and set /setprivacy off to read groups. That is the manual path for the Nous Research hermes-agent runtime, which is the Hermes this page connects, and the AIO's claim that you will always need a bot token is correct: Telegram's Bot API requires one. What ClawLink removes is everything around it. You still get the token from @BotFather, but you paste it into ClawLink once, it is stored server-side, and the 18 tools below work from chat with no gateway to start, no env file to edit, and no user-ID lookup.
The other ways Hermes Agent gets Telegram
Every route below pairs the same hermes-agent runtime; what differs is where the token lives and what you keep running.
- The BotFather + gateway route the AI Overview teaches: create the bot, copy the token, look up your numeric user ID with @userinfobot, put both in env vars, start the gateway, /setprivacy off for groups. You run a process and maintain a config file.
- n8n / Make / no-code templates: Telegram nodes and bot flows you configure in a workflow tool. They still need a BotFather token and a place to run.
- Self-hosted Telegram MCP servers: Telethon/MTProto servers such as Better Telegram MCP or chigwell/telegram-mcp that you run yourself; the bot-token ones need your token, and the user-account ones use sessions that are a different access model entirely.
- ClawLink (this page): all 18 tools over the official Bot API, token stored server-side, nothing running on your machine.
Using OpenClaw as well? The OpenClaw Telegram Bot integration is the same bot-token connection and the same tools, with OpenClaw's skill flow instead of Hermes pairing.
What the Hermes Agent Telegram Bot integration can do
18 Telegram Bot tools are ready for Hermes Agent once the account is connected. The 17 below are the ones people reach for most; your agent can call all 18.
17 of 18 Telegram Bot tools for Hermes
| Tool | What it does |
|---|---|
Answer callback query telegram_answer_callback_query | Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. |
Create chat invite link telegram_create_chat_invite_link | Generate a new primary invite link for a chat; any previously generated primary link is revoked. |
Edit message telegram_edit_message | Edit text messages sent by the bot. Only bot-authored messages can be edited; editing messages from other users will fail. In groups, the bot must have edit permissions. |
Forward message telegram_forward_message | Forward messages of any kind. Service messages can't be forwarded. |
Get chat telegram_get_chat | Get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.). |
Get chat administrators telegram_get_chat_administrators | Get a list of administrators in a chat. On success, returns an Array of ChatMember objects containing information about all chat administrators except other bots. |
Get chat history telegram_get_chat_history | Get chat history messages via the getUpdates polling method, filtered by chat_id. Returns only updates from the specified chat. |
Get chat member telegram_get_chat_member | Get a chat member's status/role (including the bot itself) to preflight permissions and troubleshoot 403/empty-history issues. Use before sending messages to verify bot membership and permissions. |
Get chat members count telegram_get_chat_members_count | Get the number of members in a chat. The bot must be an administrator in the chat for this to work. Insufficient admin permissions surface as authorization errors, not as a zero or empty count. |
Get me telegram_get_me | Get basic information about the bot using the Bot API getMe method. Returns fields like id, username, first_name, and capabilities. |
Get updates telegram_get_updates | Use this method to receive incoming updates using long polling. An Array of Update objects is returned. IMPORTANT: This method will not work if an outgoing webhook is set up. |
Send document telegram_send_document | Send general files (documents) to a Telegram chat using the Bot API |
Send location telegram_send_location | Send point on the map location to a Telegram chat using the Bot API |
Send message telegram_send_message | Send a text message to a Telegram chat using the Bot API |
Send photo telegram_send_photo | Send photos to a Telegram chat using the Bot API |
Send poll telegram_send_poll | Send a native poll to a Telegram chat using the Bot API |
Set my commands telegram_set_my_commands | Use this method to change the list of the bot's commands |
Try it: find the Telegram Bot tool you need
Browse the 17 Telegram Bot tools
Click any tool to see exactly what Hermes can do and copy a ready-to-use prompt.
Example prompts
Use telegram_get_chat to confirm the bot can see the chat I name, then telegram_send_message the text I paste to it. Confirm the message id before you finish.
Use telegram_get_chat_history on the chat I name and summarize the last 15 messages. If the bot joined after some of them, tell me where the history starts.
Use telegram_create_chat_invite_link for the group I name and give me the link. Then run telegram_get_chat_administrators and tell me who moderates it.
Use telegram_send_poll in the chat I name with the question and options I paste next. Keep it non-anonymous and tell me the poll id.
Telegram tool behaviour worth knowing
The 18 tools wrap the Bot API; these are the constraints built into their schemas.
telegram_get_updatesandtelegram_get_chat_historyuse long polling, not webhooks. The schema warns that get_updates will not work if an outgoing webhook is set up; the two are mutually exclusive, and an active webhook produces a 409 conflict. A bot with a webhook configured elsewhere must have it removed before these tools can read.telegram_get_chat_historyonly sees what the bot could see after joining. The schema states that the bot can only retrieve messages sent after it joined the chat; missing older messages is expected, and an empty ok=true result means no accessible messages, not a failure.telegram_get_meis the token health check. Its schema states that ok=false means the bot token is invalid or revoked and must be replaced before any other API call works.telegram_get_chat_members_countrequires an administrator. The schema is explicit that the bot must be an admin in the chat, and that insufficient admin permissions surface as authorization errors, not as a zero count.telegram_delete_messagehas a 48-hour limit in groups. The schema lists it: messages older than 48 hours in groups, forwarded messages, and protected-chat content cannot be deleted, returning a 400.
ClawLink vs. building it yourself
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Telegram Bot working from chat.
| Manual | ClawLink | |
|---|---|---|
| Credential handling | Collect, validate, store, and rotate the Telegram Bot API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Telegram Bot account becomes available to the agent without you building credential management. |
| Ongoing maintenance | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Telegram Bot. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| Agent usability | You still need to expose the right Telegram Bot actions to the runtime in a format your agent can reliably use. | 18 tools for Telegram Bot are already exposed through ClawLink, so the agent can read and act from chat immediately. |
ClawLink vs. Composio
Composio also exposes Telegram Bot to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Telegram Bot in the browser, and the 18 tools above work from chat. There is no SDK and no config file, and the Telegram Bot key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full Composio alternatives comparison.
Troubleshooting
Hermes paired but still can't use Telegram Bot
Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.
Connection succeeds but no tools appear
Reconnect Telegram Bot from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.
"Tool schema not loaded yet" error when calling Telegram Bot tools
Telegram Bot tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Telegram Bot call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.
Telegram Bot returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.
telegram bot api 401 unauthorized
Two different worlds share this error and the search results mix them up. In the self-hosted world a 401 means the token in the env file is malformed, revoked, or from the wrong bot, and the fixes are token surgery: re-copy, check for trailing spaces, curl getMe. In this hosted world the token is stored server-side, so there is no file to inspect; a 401 means the stored token was revoked or regenerated at @BotFather. The fix is to reconnect Telegram from the ClawLink dashboard and paste the current token. The one thing worth checking first is that the token was copied completely, because a truncated token fails exactly like a revoked one.
Ask the agent to diagnose it:
Call telegram_get_me and report exactly what it returns. If it returns ok=false, the stored token is invalid; tell me to reconnect with a fresh token from @BotFather.telegram api 429 too many requests
Telegram's Bot API throttles floods and the response carries a retry_after value; honoring it is the fix. The numbers floating around the search results (one message per second, twenty per minute in groups) describe direct Bot API usage, and are not claimed here as this connection's limits, because the hosted toolkit's rate posture belongs to the backend, not to anything on this page. What is true regardless: a prompt that fires many sends at once trips the limit, and pacing the work fixes most occurrences. Reconnecting changes nothing for a 429.
Ask the agent to diagnose it:
Report the exact status and any retry_after value from the failed Telegram call. Do not retry until that interval has passed.telegram bot token invalid
The canonical debug for this is curl https://api.telegram.org/bot\<TOKEN>/getMe, and this integration has the same check built in: telegram_get_me returns ok=false when the token is invalid or revoked, and the tool's schema says the token must be replaced before any other API call works. In the manual flow you fix the env file; here you reconnect from the ClawLink dashboard with a fresh token. @BotFather's /token issues a new token and /revoke kills the old one, which is also the fastest way to lock an agent out.
Ask the agent to diagnose it:
Call telegram_get_me. If it returns ok=false, tell me the token is invalid and that I should reconnect with a fresh one from @BotFather.API key setup works but results look incomplete
Double-check that the API key for Telegram Bot has the right scopes or account access. A valid key can still be too limited for some reads or writes.
FAQ
Is there a Hermes Agent Telegram Bot integration?
Yes. ClawLink is the fastest way to connect Hermes to Telegram Bot: link your Telegram Bot account once in the browser and Hermes Agent can call the Telegram Bot API through 18 ready-made tools — no custom code or token handling.
How do I connect Telegram Bot to Hermes with ClawLink?
Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Telegram Bot in the dashboard and Hermes can use it from the next message — no config files, and the Telegram Bot key you paste is stored server-side instead of in your environment.
How long does it take to connect Telegram Bot to Hermes Agent?
About two minutes. Sign in, click Connect next to Telegram Bot in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.
Why use ClawLink instead of wiring Telegram Bot up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Telegram Bot working from chat.
Do I need a bot token from @BotFather?
Yes, and no page claiming otherwise is describing Telegram. The Bot API requires a bot token, which means a bot created with @BotFather; the AI Overview's "you will always need a Telegram Bot Token if you are hosting or building your own custom bot" is correct. The claim on this page is narrower and true: you paste it once instead of managing it. There is no env file, no config edit, no gateway restart, and the token is stored server-side rather than on your machine. If you already have a bot, @BotFather's /token returns its token and you can paste that one.
What is the difference between this and the gateway flow the guides teach?
The guides pair the same Nous Research hermes-agent runtime with a gateway: env vars, hermes gateway setup, a restart on every change, and for group reads /setprivacy off. ClawLink runs that plumbing for you. You create the bot once, paste the token into ClawLink, and the agent calls the Bot API through the 18 tools from chat. Nothing runs on your machine, and there is no hermes gateway setup command in this flow at all.
Is it safe to connect Telegram to an AI agent?
The safety answers split into two halves. Token hygiene: the token is stored server-side, and if you lose trust in the setup, /revoke at @BotFather kills the bot immediately, which kills the connection with it. Behaviour: an agent reading group messages is reading text written by other people, and that text can carry prompt-injection attempts. Restrict the bot to the chats you name for it, keep it out of groups it does not need, and require manual approval before high-risk actions such as sending to a large group or editing messages it did not write.
Can the agent use my personal Telegram account?
No. This integration connects a bot, and the connection's own description says so: it connects a bot, not your personal account. The no-bot-token route some guides teach (Telethon user sessions, QR login) is a different thing entirely, and it is not what this page does; if you want Telegram access without running anything yourself, the bot-token connection here is the route that uses Telegram's official Bot API.
Hermes paired but still can't use Telegram Bot
Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.
