How to launch a Telegram bot

Steps

1. Create the bot in @BotFather

   Open @BotFather in Telegram and send /newbot. It asks for a name and a username; the username must end in bot. It replies with a token, a long string with a colon in it. The token is the bot's password: anyone who has it controls the bot.

   You:        /newbot
   BotFather: Alright, a new bot. How are we going to call it?
   You:        Coffee Helper
   BotFather: Choose a username. It must end in "bot".
   You:        coffee_helper_bot
   BotFather: Done! Use this token to access the HTTP API: 123456789:AA…

2. Prepare the folder and install the library

   A virtual environment keeps the bot's packages apart from the system's. The library needs Python 3.10 or newer; Ubuntu 24.04 ships a newer one.

   $ sudo apt install -y python3-venv
   $ mkdir ~/bot && cd ~/bot
   $ python3 -m venv .venv
   $ .venv/bin/pip install python-telegram-bot

3. Put the token in .env

   Keep the token out of the code. The file is readable by you only, and git never sees it.

   $ echo 'BOT_TOKEN=123456789:AA…' > .env
   $ chmod 600 .env
   $ echo '.env' >> .gitignore

4. Write the bot

   This bot answers /start and repeats any text message. It follows the echo bot from the library's own examples. Save it as bot.py.

   # bot.py
   import os
   from telegram import Update
   from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters
   
   async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
       await update.message.reply_text("Hi! Send me a message and I will repeat it.")
   
   async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
       await update.message.reply_text(update.message.text)
   
   def main() -> None:
       app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
       app.add_handler(CommandHandler("start", start))
       app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
       app.run_polling()
   
   if __name__ == "__main__":
       main()

5. Run it once by hand

   Load the token into the shell, start the script, then write to your bot in Telegram. It must answer. Stop it with Ctrl+C.

   $ set -a; source .env; set +a
   $ .venv/bin/python bot.py

6. Make it a systemd service

   Create the unit file, then enable it. Restart=always brings the bot back after a crash, and enable starts it on every boot. Replace dev with your user name.

   $ sudo nano /etc/systemd/system/telegram-bot.service
   
   [Unit]
   Description=My Telegram bot
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   User=dev
   WorkingDirectory=/home/dev/bot
   EnvironmentFile=/home/dev/bot/.env
   ExecStart=/home/dev/bot/.venv/bin/python bot.py
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   
   $ sudo systemctl daemon-reload
   $ sudo systemctl enable --now telegram-bot

Long polling or webhook

The bot above uses long polling: it keeps asking Telegram "any news?" and Telegram answers when a message arrives. It needs no public address, so it works on a laptop behind a home router. A webhook turns this around: Telegram sends each message to an https address you register, and your bot answers the request.

To switch, install the webhook extra with pip install "python-telegram-bot[webhooks]" and replace the last line of main(). The secret makes Telegram add the header X-Telegram-Bot-Api-Secret-Token to every request, so your bot can ignore anyone else.

# instead of app.run_polling()
app.run_webhook(
    listen="0.0.0.0",
    port=8080,
    url_path="telegram",
    webhook_url="https://bot.example.com/telegram",
    secret_token=os.environ["WEBHOOK_SECRET"],
)

Check that it works

Ask systemd for the status, then watch the log while you write to the bot. Reboot once to see it come back by itself.

$ sudo systemctl status telegram-bot
Active: active (running)
$ journalctl -u telegram-bot -f
$ sudo reboot

Common problems