Skip to content

Host a Telegram bot

An AI Telegram bot that runs all the time. The bot token stays with exe.dev.

Deploy on 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/stdin

An 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 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.
What's running, and where
Shared Telegram the bot, for you and the people you invite
Private https://telegram.int.exe.xyz/ the Bot API as your bot, from this VM only
Private ssh my-telegram-bot.exe.xyz code, prompt, logs
my-telegram-bot.exe.xyz exe.dev VM
bot.py one Python file on python-telegram-bot 22.8, run by uv as telegram-bot.service ~/telegram-bot
SQLite each chat's recent messages, who may use the bot, open groups ~/telegram-bot/data/bot.db
Telegram integration telegram.int.exe.xyz adds the bot token to Bot API calls and file downloads
LLM integration 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/stdin
What 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 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; /open lets everyone in that group use it, and /close undoes that.
  • /invite gives you a one-time link for one more person.
  • /forget clears 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
&lt; &gt; &amp;. 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.
  • Unauthorized or 401: 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 run curl -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: getWebhookInfo shows last_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/telegram should 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 in prompt.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