# How to connect Telegram Bot to Hermes Agent (paste one key, 18 tools)

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

Web version: https://claw-link.dev/hermes/telegram

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.

**Start here — paste this into Hermes to set up ClawLink:**

> 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 with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 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.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Telegram Bot** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect telegram  # connect Telegram Bot (browser OAuth)
npx -y @useclawlink/cli actions telegram  # list available actions
npx -y @useclawlink/cli run telegram <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
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 test
```

Then connect Telegram Bot in the [ClawLink dashboard](https://claw-link.dev/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:

```bash
npx -y @useclawlink/cli login
```

`login` 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](https://claw-link.dev/learn/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](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Telegram Bot integration](https://claw-link.dev/openclaw/telegram) 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](https://claw-link.dev/openclaw/telegram) 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 |

## Example prompts

**Reply in a chat**

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

**Summarize a chat**

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

**Invite link for a group**

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

**Send a poll**

> 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_updates` and `telegram_get_chat_history` use 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_history` only 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_me` is 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_count` requires 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_message` has 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](https://claw-link.dev/hub/composio-alternatives) comparison.

### 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:

```text
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:

```text
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\/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:

```text
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.

### 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`.

## Related

- [SendGrid](https://claw-link.dev/hermes/sendgrid) — Deliver transactional and marketing emails
- [Connect Dialpad](https://claw-link.dev/hermes/dialpad) — Business phone, messaging, and video conferencing
- [Connect Discord Bot](https://claw-link.dev/hermes/discord-bot) — Automate Discord server actions with bot-specific permissions