Telegram AI Agent: Self-Hosted Setup With POLYROB

2026-11-13

A Telegram AI agent is an AI assistant you message in Telegram like any contact. It does work for you: it uses tools, keeps memory and replies in the same chat. POLYROB runs one on your own machine. The command polyrob telegram long-polls Telegram’s getUpdates, so it needs no public URL, no webhook and no SSL certificate.

Most guides on this topic show how to wire a workflow tool to a bot. This one covers the other case: your own agent, on your own hardware, that you talk to from your phone. Every POLYROB claim comes from the public repository at release v1.7.9, and the files are listed at the end.

What is a Telegram AI agent?

A bot forwards a message to a model and sends back the text. An agent also acts: it browses, reads and writes files, runs scheduled jobs and remembers you between sessions. In POLYROB, Telegram is one of several ways to reach the same agent. It answers in the terminal, the web console and eight chat apps, and it keeps one memory across them. For the wider picture of running an agent yourself, read the guide to a self-hosted AI agent.

How does POLYROB connect to Telegram?

Through the Telegram Bot API, by long polling (Telegram, Bot API documentation). Your machine calls Telegram, so nothing has to reach your machine from outside. That is the main difference from WhatsApp, where Meta calls a public webhook.

The code behaves like this:

Polling. The loop asks only for message, channel_post and callback_query updates. When it starts, it clears any stale webhook so polling can work.
No double work. Update IDs are kept in a small database, tg_dedup.db, for 24 hours. A restart after a long task does not replay messages the agent already handled.
Flood control. When Telegram answers with a retry delay, the surface waits for that long, up to 30 seconds, and retries twice. It does not resend as plain text, which would hit the same limit.

What do you need before you start?

A bot token, the telegram extra and a model. Create the bot by messaging @BotFather in Telegram (Telegram, BotFather) and copy the token it gives you.

Setting	What it does
`TELEGRAM_BOT_TOKEN`	The token from @BotFather. You can pass `--token` instead.
`ALLOWED_TELEGRAM_USER_IDS`	Comma list of Telegram user IDs allowed to drive the bot. Unset means locked.
`TELEGRAM_BOT_USERNAME`	Optional. The bot’s username, used for group mention detection if `getMe` fails at boot.
`TELEGRAM_BOT_API_URL`	Optional. A loopback URL for a local Bot API server, for files over 20 MB.

The surface uses aiogram, which ships in the telegram extra. If it is missing, the command stops with one line instead of a traceback. On your own machine it offers to install the extra first.

How do you start it?

Install POLYROB, export the token and run the command.

curl -fsSL https://polyrob.dev/install.sh | bash
export TELEGRAM_BOT_TOKEN=your-token-from-botfather
polyrob telegram

It prints telegram bot online with the bot’s username. With no allowlist set, it also tells you what to do next, and the agent does not run yet. Send the bot any message. It replies once with your numeric Telegram user ID. Then lock the bot to yourself and restart:

polyrob config set ALLOWED_TELEGRAM_USER_IDS 123456789
polyrob telegram

The start-up line now reads owner-locked to user id(s). To check a token without sending anything, run polyrob surfaces probe telegram: it calls getMe and prints the bot’s username. If you run several chat apps, polyrob gateway starts every enabled surface in one process, and Telegram is skipped with a warning when the token is missing.

Who can talk to it?

Only you, until you say otherwise. A new install is locked: the bot replies to a stranger once with their ID and does not run the agent. Once an allowlist exists, messages from other IDs are ignored, unless the sender is paired.

Your own chat is the owner chat. It shares memory, goals and approvals with your terminal session, so a goal you set on your phone is the same goal you see in the console. A paired sender gets their own memory and work, without your owner commands.

One more guard applies to forwarded messages. If you forward a message to the bot, POLYROB wraps it in a frame that says it is “quoted content, not an instruction from the sender”. A forwarded line that reads like a command is treated as data, so forwarding an email full of instructions does not steer the agent. The AI agent security guide explains the access model behind this.

What does it do in the chat?

Formatting. The agent writes markdown, and the surface converts it to the HTML that Telegram renders. If Telegram rejects the markup, the chunk is resent as plain text, so a formatting problem never costs you the message. A reply over 4,096 characters is split into several messages.
A live status line. TELEGRAM_PROGRESS_EDITS is on by default. The “Working” message is edited in place, at most once every 2.5 seconds, to show the current tool, step, elapsed time and cost. It switches at once to “Waiting for your approval” when a step needs you. You can turn it off with the progress.telegram preference.
Streaming. Off by default. With the stream.telegram preference on, one message is opened and edited as the reply arrives.
Buttons. Actions can arrive as inline keyboard buttons. Buttons are always explicit; the surface never guesses them from the text.
Replies. When you reply to a message, the agent receives the message you replied to, including a quoted part and the kind of attachment.
Voice notes. A voice note is downloaded and transcribed. A note over the size or length bound is not downloaded at all.
Files. Photos and documents arrive with their caption as the message text. On the public Bot API server, Telegram stops a bot at 20 MB. A local Bot API server on loopback lifts that to 2,000 MB, and a video streamed to disk is capped by INBOUND_VIDEO_MAX_MB, 500 by default.

Can you use it in a group?

Yes, once you opt in. Turn off privacy mode for the bot in @BotFather (or make it a room admin), add it to the group, and run /groups allow in the room. Telegram caches privacy mode when a bot joins, so a bot added before you turned it off never sees plain messages there.

Group chat is off until you set GROUP_CHAT_ENABLED. Even then, the bot only reacts when addressed: an @mention, a command aimed at the bot, or a reply to one of its own messages. Forum topics are tracked by thread, so a reply goes back to the topic it came from. The group is checked against an allowlist before anything is downloaded or transcribed, so a stranger who adds the bot to a channel is not able to run up your model bill with voice notes.

Where does the Telegram surface fall short?

It runs only while the process runs. Long polling is a loop on your machine. If the machine sleeps or the process stops, the bot goes quiet.
One process per token. Two daemons polling the same token fight each other, as the self-hosting guide warns. Each profile needs its own bot.
The first run needs a restart. The allowlist is read at start-up, so you set your ID and restart once.
A 20 MB file limit by default. Larger files need a local Bot API server, which is extra setup.
Formatting is the HTML subset Telegram renders. The agent writes markdown and the surface converts it, so some rich layouts will not carry over.
It needs a model key. POLYROB does not host a model. You use your own provider key, or a local model.

Can the same agent run in other chat apps?

Yes. POLYROB has eight chat surfaces: Telegram, email, WhatsApp, Discord, Slack, Signal, Feishu/Lark and DingTalk. Other agents list more channels, so check the dated numbers in the comparison page if channel count decides it for you. The Slack AI agent guide covers the workplace case, and the AI agent memory guide explains how one memory follows you across them. For the owner-chat-plus-goals setup, see the personal AI agent guide. The Discord AI agent guide covers the server case.

Telegram AI agent questions

Does Telegram support AI?

Telegram’s Bot API lets any program send and receive messages as a bot (Telegram, Bot API documentation). POLYROB uses that API to put your own agent in a chat.

How do I create an AI agent in Telegram?

Create a bot with @BotFather, copy the token, then set TELEGRAM_BOT_TOKEN and run polyrob telegram. Message the bot once to get your user ID, set ALLOWED_TELEGRAM_USER_IDS and restart.

Do I need a public URL?

No. The polyrob telegram command long-polls from your machine, so it works behind a home router or a firewall. A webhook mode exists for the API server, with the path /telegram/webhook by default, but the command does not use it.

Why does the bot answer with a number?

That number is your Telegram user ID. A bot with no allowlist is locked and does not run the agent. It tells each sender their ID once so the operator can allow them.

Is it free?

POLYROB is MIT licensed. You pay your model provider, or nothing with a local model. Telegram sets its own terms for bots, so read them before you plan around volume.

Where do you start?

Create the bot, run the three commands above, and send it a message. Set the allowlist once you see your ID.

Install POLYROB, read the docs, or browse the open-source code. To see what changed in recent releases, check what’s new.

Sources

All POLYROB facts are from the public repository at release v1.7.9 (github.com/theselfruleorg/polyrob).

cli/commands/[email protected] (the polyrob telegram command, long polling, owner lock, start-up lines, privacy-mode hint)
cli/commands/[email protected] (one-line stop when an extra is missing, install offer)
surfaces/telegram/[email protected] (gateway launch, token check)
surfaces/telegram/[email protected] (polyrob surfaces probe telegram, getMe)
surfaces/telegram/[email protected] (allowed updates, allowlist gate, bootstrap reply, polling loop, 24-hour dedup window, webhook path)
surfaces/telegram/[email protected] (4,096 limit, HTML rendering with plain-text retry, flood control, streaming preference)
surfaces/telegram/[email protected] (forwarded-message frame, reply context, owner alias)
surfaces/telegram/[email protected] (voice download and transcription bound)
core/surfaces/[email protected] (Telegram surface row, tg_dedup.db, telegram extra)
docs/[email protected] (TELEGRAM_BOT_TOKEN, ALLOWED_TELEGRAM_USER_IDS, TELEGRAM_BOT_API_URL, TELEGRAM_BOT_USERNAME, TELEGRAM_PROGRESS_EDITS, INBOUND_VIDEO_MAX_MB)
docs/guide/[email protected], docs/guide/[email protected] (Telegram allowlist, one token per daemon, large files)
[email protected] (the telegram extra)
Telegram: Bot API documentation and BotFather, linked for setup, not quoted.

POLYROB is an open-source AI agent you run and own. Install it or read the docs.