Host a Telegram bot
An AI Telegram bot that runs all the time. The bot token stays with exe.dev.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/telegram-bot/prompt.txt | ssh exe.dev new --prompt=/dev/stdinAn AI Telegram bot that answers you and the people you invite, reads the photos, PDFs, and files you send it, and remembers each conversation. It's one Python file on python-telegram-bot, running all the time on an exe.dev VM under systemd, with its memory in SQLite on the VM's disk.
No secret lives on the VM. exe.dev's Telegram integration keeps the bot token and adds it to each Bot API call on the way out; the LLM integration does the same for Claude. The bot long-polls Telegram, so it needs no public URL either: the VM stays private behind exe.dev login. The same setup runs any other bot code, in any language, as the last sections show.
What you get#
telegram-bot.service, restarted on failure and reboot, long-polling Telegram through the integration and loggingconnected to Telegram as @<bot>.- Claude answering in private chats, and when mentioned or replied to in groups, with each chat's last 20 messages remembered in SQLite.
- Photos, PDFs, and text files sent to the bot downloaded through the integration's
/file/path and read by the model. - The bot token held by exe.dev's Telegram integration and models from the LLM integration, with neither secret on the VM.
- The bot claimed by its owner through a one-time link, and ignoring everyone they haven't invited.
What's running, and where
Telegram
the bot, for you and the people you invite
https://telegram.int.exe.xyz/
the Bot API as your bot, from this VM only
ssh my-telegram-bot.exe.xyz
code, prompt, logs
telegram-bot.service
telegram.int.exe.xyz adds the bot token to Bot API calls and file downloads
llm.int.exe.xyz, Claude Sonnet 5.5 by default
Deploy with Shelley#
Click Deploy and Shelley will set up Telegram bot on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe-staging.dev/deploy/telegram-bot/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
Set up Telegram bot on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/telegram-bot.md?via=deploy from top to bottom.
The recipe's example VM name is my-telegram-bot. This VM's name is the output of `hostname`: use it wherever the recipe writes my-telegram-bot. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- `telegram-bot.service`, restarted on failure and reboot, long-polling Telegram through the integration and logging `connected to Telegram as @<bot>`.
- Claude answering in private chats, and when mentioned or replied to in groups, with each chat's last 20 messages remembered in SQLite.
- Photos, PDFs, and text files sent to the bot downloaded through the integration's `/file/` path and read by the model.
- The bot token held by exe.dev's Telegram integration and models from the LLM integration, with neither secret on the VM.
- The bot claimed by its owner through a one-time link, and ignoring everyone they haven't invited.
Read the whole recipe, closed details included, and follow "Set up by
hand" in order, skipping VM creation; the walkthrough above it is for
the owner. The bot token must never be on this VM: don't ask for it.
First give the owner the steps in "Make a bot" and "Give exe.dev the
token", with the connect link for this VM's name, and install the bot
while they do that; the service retries until the integration is
attached. If `curl -s https://reflection.int.exe.xyz/integrations` shows
their Telegram integration under a name other than `telegram`, set
TELEGRAM_API in ~/telegram-bot/bot.env to match. When the log shows the
owner link, give it to the owner. Stay with long polling unless they ask
for webhooks. End with the owner link, what to try, and how to change
the prompt.
Finish with the URLs I should open.
Also at /deploy/telegram-bot/prompt.txt. The recipe it follows is /deploy/telegram-bot.md.
Make a bot#
In Telegram, open @BotFather, send /newbot,
and answer its two questions: a display name, and a username that ends in
bot. It replies with the bot's token, a line like
123456789:AAH.... You'll hand it to exe.dev in the next step; don't put
it anywhere else.
Give exe.dev the token#
Open the connect link for your VM,
exe.dev/integrations/add?service=telegram&attach=vm:my-telegram-bot,
name it telegram, paste the token, and add it. Then delete the
token from your BotFather chat, or wherever else you pasted it. (Over
SSH, ssh exe.dev integrations list --available prints the command that
adds a telegram integration instead; see
Integrations.)
On the VM, the bot's API is now https://telegram.int.exe.xyz:
curl -s https://telegram.int.exe.xyz/getMe
prints "ok":true and your bot's username. The token isn't in the URL,
and it isn't anywhere on the VM.
Claim your bot#
The first time it starts, the bot logs a one-time link that makes whoever opens it the bot's owner. Shelley gives it to you; or, on the VM:
journalctl -u telegram-bot | grep -o 'https://t.me/[^ ]*' | tail -1
Open it on a device with Telegram and press Start. The bot says hi. Anyone else who messages it gets "This bot is private".
Talk to it#
- In a private chat, just write. Follow-ups work: it remembers the chat's last 20 messages.
- Send a photo, a PDF, or a text file, with a question as the caption. The bot downloads it through the integration and Claude reads it.
- In a group, add the bot, then mention it (
@yourbot what's...) or reply to one of its messages. Invited people can use it anywhere;/openlets everyone in that group use it, and/closeundoes that. /invitegives you a one-time link for one more person./forgetclears what it remembers of the chat.
While Claude works, the chat shows "typing…". Replies use Telegram's formatting: bold, italics, code, links.
Make it yours#
The bot's instructions are in ~/telegram-bot/prompt.md; its settings,
including MODEL, in ~/telegram-bot/bot.env. Change either, then
sudo systemctl restart telegram-bot.
Shelley, the agent on the VM, can change the bot itself: "add a /summary
command", "send me the weather every morning at 7", "answer voice notes".
bot.py is short and
commented, and the integration passes every Bot API method through.
Run your own bot code#
The integration is the Bot API at a different address, without the token.
Where Telegram's docs say https://api.telegram.org/bot<token>/METHOD,
call https://telegram.int.exe.xyz/METHOD; where they say
https://api.telegram.org/file/bot<token>/<file_path>, call
https://telegram.int.exe.xyz/file/<file_path>. With curl, on the VM:
curl -s https://telegram.int.exe.xyz/getUpdates # find a chat_id
curl -s https://telegram.int.exe.xyz/sendMessage -d chat_id=123456789 -d text='Deployed!'
That's also the simplest way to send yourself alerts from cron jobs and
scripts. Libraries need their base URL changed, and most insist on some
token; give them a placeholder, which never leaves the VM. Each snippet
below was tested through the integration, with getMe and a file
download, at the version shown:
python-telegram-bot 22.8. A plain string base_url gets the token
appended, so pass a function:
API = "https://telegram.int.exe.xyz"
app = (ApplicationBuilder().token("exe-dev-integration")
.base_url(lambda _: API).base_file_url(lambda _: API + "/file").build())
aiogram 3.32. aiogram checks the token's shape and takes the bot's ID from it, so use your bot's numeric ID (the part of the token before the colon) and anything after it:
from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
API = "https://telegram.int.exe.xyz"
session = AiohttpSession(api=TelegramAPIServer(base=API + "/{method}", file=API + "/file/{path}"))
bot = Bot(token="123456789:exe-dev-integration", session=session)
pyTelegramBotAPI (telebot) 4.37. It also wants <digits>:<anything>:
import telebot
from telebot import apihelper
apihelper.API_URL = "https://telegram.int.exe.xyz/{1}"
apihelper.FILE_URL = "https://telegram.int.exe.xyz/file/{1}"
bot = telebot.TeleBot("123456789:exe-dev-integration")
For AsyncTeleBot, set the same two names on telebot.asyncio_helper.
grammY 1.46 (tested on Node.js 24):
import { Bot } from "grammy";
const API = "https://telegram.int.exe.xyz";
const bot = new Bot("exe-dev-integration", {
client: { apiRoot: API, buildUrl: (root, _token, method) => `${root}/${method}` },
});
// files: fetch(`${API}/file/${(await ctx.getFile()).file_path}`)
Telegraf has no way to drop the token from its URLs, and hasn't had a
release since February 2024; prefer grammY. Bots in other languages work
the same way if their library takes an API base URL; the Go
telegram-bot-api
has NewBotAPIWithAPIEndpoint, whose endpoint is a format string.
Run your bot under systemd as in Set up by hand, with
its own ExecStart, and keep its state in a file on the VM's disk
(SQLite is plenty; see SQLite).
Switch to webhooks#
With a webhook, Telegram POSTs each update to your HTTPS URL instead of
the bot asking for them. On exe.dev that's the VM's own address,
https://my-telegram-bot.exe.xyz/, which the HTTPS proxy
sends to port 8000 (Telegram only calls ports 443, 80, 88, and 8443, so
use that one rather than :8443). It has to be public, so Telegram can
reach it. On your computer:
ssh exe.dev share set-public my-telegram-bot
On the VM, switch the bot over and restart it:
cd ~/telegram-bot
printf 'MODE=webhook\nPUBLIC_URL=https://%s.exe.xyz\n' "$(hostname)" >> bot.env
sudo systemctl restart telegram-bot
curl -s https://telegram.int.exe.xyz/getWebhookInfo; echo
The bot serves /telegram on port 8000 and calls setWebhook through
the integration with a random secret_token it keeps in
data/webhook-secret. Telegram sends that secret in the
X-Telegram-Bot-Api-Secret-Token header of every update, and the bot
rejects requests without it, so nobody else can feed it updates.
getWebhookInfo should show your URL and "pending_update_count":0.
To check the secret from your computer (not from the VM, which can't
reach its own public address), curl -s -o /dev/null -w '%{http_code}\n' -X POST https://my-telegram-bot.exe.xyz/telegram should print 403.
To go back, delete the two lines from bot.env and restart: the bot
removes the webhook when it starts polling. Then
ssh exe.dev share set-private my-telegram-bot.
The nuts and bolts#
These are Shelley's setup steps and your maintenance reference.
Set up by hand
Create the VM#
On your computer (pick another name if my-telegram-bot is taken):
ssh exe.dev new --name=my-telegram-bot
Then do Make a bot and
Give exe.dev the token. The rest runs on the
VM (ssh my-telegram-bot.exe.xyz).
Install the bot#
bot.py declares its one
dependency, python-telegram-bot[webhooks]==22.8, inline; uv installs
it, and a Python to run it, on first start.
mkdir -p ~/telegram-bot && cd ~/telegram-bot
curl -fsSL https://exe-staging.dev/deploy/telegram-bot/bot.py -o bot.py
cat > prompt.md <<'EOF'
You are a helpful assistant in Telegram. Messages start with the sender's
first name. Answer briefly and in plain language. Format with Telegram's
HTML only: <b>, <i>, <code>, <pre>, <a href="...">, and plain line breaks;
no Markdown, headings, tables, or other tags. Escape <, > and & in text as
< > &. Keep replies under 3,000 characters unless asked for more.
EOF
cat > bot.env <<'EOF'
TELEGRAM_API=https://telegram.int.exe.xyz
MODEL=claude-sonnet-5-5
EOF
TELEGRAM_API is the integration's URL: https://<name>.int.exe.xyz
for an integration called <name>.
Run it under systemd#
sudo tee /etc/systemd/system/telegram-bot.service >/dev/null <<'EOF'
[Unit]
Description=AI Telegram bot (exe.dev/deploy/telegram-bot)
After=network-online.target
Wants=network-online.target
[Service]
User=exedev
WorkingDirectory=/home/exedev/telegram-bot
EnvironmentFile=/home/exedev/telegram-bot/bot.env
ExecStart=/usr/local/bin/uv run --script bot.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now telegram-bot
Until the integration is attached, the log shows integration not found
and systemd restarts the bot every 10 seconds.
Check it#
curl -s https://telegram.int.exe.xyz/getMe; echo
journalctl -u telegram-bot -n 20 --no-pager
The first prints the bot. The log should say
connected to Telegram as @<your bot>, then the owner link (until someone
has used it).
Back up and move
Everything is in ~/telegram-bot: the code, prompt.md, bot.env, and
data/bot.db, which holds who may use the bot, the open groups, and each
chat's recent messages. Back it up to keep your invitations; losing it
means claiming the bot again. Nothing in it lets anyone control the bot.
On your computer:
ssh my-telegram-bot.exe.xyz 'sqlite3 telegram-bot/data/bot.db ".backup /tmp/bot.db" && tar -czf - -C ~ --exclude=data telegram-bot -C /tmp bot.db' > telegram-bot.tar.gz
To restore on a new VM, attach the integration to it
(ssh exe.dev integrations attach telegram vm:new-vm), set up the
systemd unit as above, then unpack:
scp telegram-bot.tar.gz new-vm.exe.xyz:
ssh new-vm.exe.xyz 'tar -xzf telegram-bot.tar.gz && mkdir -p telegram-bot/data && mv bot.db telegram-bot/data/ && sudo systemctl restart telegram-bot'
Stop the bot on the old VM first: Telegram gives updates to only one poller at a time (see Troubleshooting).
Update
On the VM, fetch the latest bot.py (this replaces local changes), and
restart:
cd ~/telegram-bot
curl -fsSL https://exe-staging.dev/deploy/telegram-bot/bot.py -o bot.py
sudo systemctl restart telegram-bot
To rotate the token, send BotFather /revoke, then paste the new token
into the integration on the Integrations page.
The VM needs no change.
Troubleshooting
Start with the log, on the VM: journalctl -u telegram-bot -n 50.
integration not found or not attached to this VM: attach it, on your computer:ssh exe.dev integrations attach telegram vm:my-telegram-bot.Unauthorizedor401: the token was revoked or mistyped; paste the current one into the integration.Conflict: terminated by other getUpdates request: another copy of the bot is polling with the same token, on another VM or your laptop. Stop it; only one poller gets updates.Conflict: can't use getUpdates method while webhook is active: something set a webhook. The bot deletes it when it starts polling, so restart it, or runcurl -s https://telegram.int.exe.xyz/deleteWebhook.- No answer in a group: mention the bot by its @username or reply to
it, and make sure you're invited or the group is
/open. The log lists ignored messages with the sender's ID. - Webhook:
getWebhookInfoshowslast_error_message: the VM isn't public (ssh exe.dev share set-public my-telegram-bot), or the bot isn't listening on port 8000 (curl -s localhost:8000/telegramshould answer, with an error, rather than refuse the connection). - Raw
<b>tags in replies: the model wrote HTML Telegram rejected, and the bot fell back to plain text. Tighten the formatting rules inprompt.md.
Frequently asked questions#
Where does the bot token live?
With exe.dev. The Telegram integration (in the integration catalog) stores it and puts it into each request the VM sends to telegram.int.exe.xyz, so the VM, its agent, and anyone who breaks into it can use the bot but can't copy the token. Detach the integration and the VM can't reach the bot at all.
Polling or webhooks?
Long polling, unless you have a reason. It needs no public URL, works the moment the integration is attached, and answers just as fast for a personal or team bot. Webhooks suit bots with heavy traffic, or code that already expects them; see Switch to webhooks.
Can I use aiogram, grammY, or my own bot?
Yes. Any library that lets you set the API's base URL works; point it at https://telegram.int.exe.xyz with a placeholder token, as in Run your own bot code. Code that builds https://api.telegram.org/bot<token>/ URLs itself needs that one line changed.
Who can talk to my bot?
Anyone can find a Telegram bot and message it, so this one answers only its owner and the people they invite, and in groups only after /open. Everyone else gets "This bot is private", and the model is never called for them.
How much does it cost?
The VM is part of your exe.dev plan, and model calls count against your exe.dev LLM allocation; Telegram's Bot API is free. Each answer sends the chat's last 20 messages to the model, plus any photo or PDF. MODEL=claude-haiku-5-5 costs about a fifth as much.
Can it use GPT or an open model?
Any model the LLM integration serves on the Anthropic Messages API: set MODEL in ~/telegram-bot/bot.env. curl -s https://llm.int.exe.xyz/models.json on the VM lists models and the APIs they speak. For GPT models, ask Shelley to switch ask_claude to the OpenAI API, which the integration also serves.
Why not Railway or a VPS?
They run a Telegram bot fine, with the token in an environment variable. Here the token never reaches the server, the SQLite file sits on a disk that stays put, models need no key, and the VM's agent can change the bot when you ask.
Updated Nov 17, 2026 · tested end to end Nov 17, 2026 · Markdown · manifest.json · Something wrong? Tell us