Connect Telegram to an agent

Connect Telegram when you want to message an agent from your phone and get its scheduled results there. The agent gets a Telegram bot of its own; you chat with that bot.

Before you start#

• A Hermes or OpenClaw agent that has finished setting up. Codex agents cannot use chat channels yet.
• The Telegram app, signed in to your own account.

Create the bot in Telegram#

Telegram bots are made by chatting with Telegram's own bot, BotFather. Telegram's guide is BotFather in the Telegram bot documentation.

1. In Telegram, open a chat with @BotFather and send /newbot.
2. Choose a display name, then a username. The username must end in bot.
3. BotFather replies with an HTTP API token that looks like 123456789:ABC-DEF…. Copy it. Treat it like a password: anyone with it can control the bot.
4. Find your own numeric Telegram user id: message @userinfobot and it replies with your Id.

How to get a Telegram bot token#

A bot token comes only from BotFather. For a new bot, send @BotFather /newbot and it replies with the token once you have picked a name and a username. For a bot you already have, send /mybots, pick the bot, then API Token, and BotFather shows the current token. If a token has leaked or you lost it, send BotFather /token and pick the bot to generate a new one, as Telegram's bot documentation describes, then paste the new token into Qoren.

How to find your Telegram user id#

Your Telegram user id is a number, such as 123456789, and it is not the same as your @username. The quickest way to see it is to open a chat with @userinfobot and send any message: it replies with your Id. Use that number, not your @username and not the bot's own id.

Connect the bot in Qoren#

1. Open the agent, click Settings, then Connections.
2. Under Channels, pick Telegram from Add a gateway…. The Telegram form opens.
3. Paste the token into Bot token (1). To use a token you saved in the Vault instead, click Use vault (2) and pick it.
4. Type your numeric id into Your Telegram user id (3).

1234

5. Click Save changes at the bottom of the page.

Both fields are required. The form checks their shape as you type: a token that does not look like a Telegram token, or an id that is not all digits, shows "Not in the expected format." and Save changes stays off until it is fixed. Help (4) opens the same steps in a dialog.

What your user id does#

The id does two jobs. It restricts who can talk to the bot, so a stranger who finds it cannot use your agent. And it is where the agent sends things on its own, such as the results of its scheduled tasks.

Test it#

1. Wait for the panel to say Saved. The agent then signs in to Telegram.
2. Under Connections, the Telegram card should turn to Connected, with the bot's username underneath.
3. Open your bot in Telegram (search for its username) and send it a message. The reply comes from your agent.

While the agent works on your message, it reacts to it with 👀, then swaps that for 👍 once it has replied. Telegram does not let bots react with ✅, the done reaction on other chat apps, so it shows 👍 instead. You can choose other reactions: see choose the chat reactions.

Fix a channel that needs attention#

If the card says Needs attention (1), the agent could not sign in, and the reason is shown underneath. A red banner with Review messaging setup also appears across the agent's tabs until it is fixed.

1

• The token was rejected. Telegram no longer accepts that token, usually because the bot was deleted or its token was revoked in BotFather. Get a fresh token from BotFather (/mybots, pick the bot, then API Token), paste it into Bot token and click Save changes.
• The bot never replies to you. Check Your Telegram user id is your own numeric id from @userinfobot, not your @username or the bot's id.
• Still Not reported yet after a while. The agent reports when it starts and after every change. If it stays that way, open what to do when an agent is not responding.

To change the token later, type the new one over "•••• set (leave blank to keep)" and save. Leaving the field blank keeps the saved token.