A Telegram bot is one of the most satisfying first projects in Python: it is quick to build, free to run, and instantly useful on a phone you already carry. In this 2026 tutorial you will create a bot, handle commands, and connect it to a free API so it can send live data on demand — all in well under 50 lines of code. It is also a project that teaches the core skills behind almost every integration: reading user input, calling an external service, handling errors, and replying with a clean result.
What You Will Build
A working Telegram bot with two commands: a /start greeting and a /catfact command that pulls a random fact from a free API and replies with it. The same pattern works for weather, news, currency rates, or any free API you like.
Prerequisites
- Python 3.10 or newer.
- The Telegram app, to talk to BotFather and test your bot.
- Basic comfort running a Python script.
Step 1: Create a Bot with BotFather
Open Telegram and search for BotFather, the official bot for making bots. Send /newbot, choose a name and a username ending in "bot", and BotFather replies with a token — a long string that authenticates your bot. Keep it secret; anyone with it can control your bot.
Step 2: Install the Library
We will use python-telegram-bot, the most popular Telegram library for Python, plus httpx for the API call:
pip install python-telegram-bot httpxStep 3: Write a Basic Bot
Create bot.py. This minimal bot replies to /start:
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text("Hello! I am your bot. Try /catfact.")
app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()Run it with python bot.py, open your bot in Telegram, and send /start. It should greet you back. The library uses async functions, so each handler is an async def.
Step 4: Add a Command That Calls a Free API
Now make the bot useful. Add a /catfact command that fetches a random fact from a free, no-key API and sends it:
import httpx
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text("Hello! I am your bot. Try /catfact.")
async def catfact(update: Update, context: ContextTypes.DEFAULT_TYPE):
try:
response = httpx.get("https://catfact.ninja/fact", timeout=10)
response.raise_for_status()
fact = response.json()["fact"]
await update.message.reply_text(fact)
except Exception:
await update.message.reply_text("Could not fetch a fact right now. Try again.")
app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CommandHandler("catfact", catfact))
app.run_polling()Send /catfact and the bot replies with a live fact pulled from the API. The try/except keeps the bot polite when the API has a hiccup instead of crashing.
Step 5: Keep Your Token Safe
Hard-coding the token is fine for a first test, but for anything you share, load it from an environment variable instead:
import os
app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()Set TELEGRAM_BOT_TOKEN in your shell, and the secret never lives in the file you commit.
Step 6: Where to Go Next
From here you can swap the cat-fact API for any free API: send the weather for a city, today's exchange rate, a news headline, or a random quote. Add more CommandHandler entries, or handle plain messages to make the bot conversational. To keep it running around the clock, deploy it to a small server or a free hosting tier so it does not stop when you close your laptop.
Ideas for Your Next Bot
The cat-fact bot is a starting point, and the same few lines open up a lot. A weather bot can take a city name and reply with the current conditions from a free weather API. A currency bot can convert amounts using a live exchange-rate API. A news bot can send the top headlines on a schedule. A reminder bot can store tasks and ping you later. A dictionary bot can define any word the user sends. Each one is the same pattern you already wrote: read the user's input, call a free API, and reply with the result. Because Telegram bots live on a phone everyone already has, they are a satisfying way to turn an API into something you actually use every day — and a great portfolio project to show employers you can wire services together.
Common Mistakes to Avoid
- Leaking the token. Never commit it or post it. If it leaks, ask BotFather to revoke and reissue it.
- Blocking calls without a timeout. Always pass a
timeoutso a slow API does not freeze the bot. - Forgetting the username rule. Bot usernames must end in "bot" — BotFather enforces it.
- Running two copies at once. Polling from two processes with the same token causes conflicts; run one instance.
Frequently Asked Questions
Is building a Telegram bot free?
Yes. Creating a bot with BotFather is free, the library is open-source, and the cat-fact API used here needs no paid plan. Running it costs nothing on your own machine.
Do I need a server?
Not to test — it runs on your computer. To keep it online all the time, deploy it to a small server or a free hosting tier.
Can the bot use any API?
Yes. Any API you can call from Python can power a command, whether it needs a key or not. A directory of free, key-optional APIs makes a great source of ideas to get started quickly.
How do I handle normal messages, not just commands?
Add a MessageHandler alongside your command handlers to respond to any text the user sends, which is how you make the bot conversational.
Wrapping Up
You built a real Telegram bot that talks to a live API, handled errors gracefully, and learned how to keep your token safe — the foundation for any bot you build next. Swap in a different free API and you have a brand-new bot in minutes.
Looking for free APIs to power your next command? Browse the full directory at Free API Hub and pick one to wire in.
