How to Build a Telegram Bot: Complete Tutorial with Code [2026]

 1my-telegram-bot/
 2├── bot.py              # Main bot file (Step 3)
 3├── handlers.py         # Message handlers (Step 3-4)
 4├── database.py         # Database operations (Step 5)
 5├── config.py           # Configuration (Step 2)
 6├── requirements.txt    # Dependencies (Step 2)
 7└── .env                # Secret token (Step 2)

 1Done! Congratulations on your new bot. You will find it at t.me/my_awesome_2026_bot.
 2
 3Use this token to access the HTTP API:
 47123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

 1start - Start the bot
 2help - Show help message
 3menu - Show main menu

 1# Create project folder
 2mkdir my-telegram-bot
 3cd my-telegram-bot
 4
 5# Create virtual environment (isolates dependencies)
 6python -m venv venv
 7
 8# Activate virtual environment
 9# Windows:
10venv\Scripts\activate
11# macOS/Linux:
12source venv/bin/activate
13
14# Install dependencies
15pip install aiogram python-dotenv aiosqlite

 1# config.py — bot configuration
 2# Loads token from .env file
 3
 4import os
 5from dotenv import load_dotenv
 6
 7# Load environment variables from .env
 8load_dotenv()
 9
10# Bot token from BotFather
11BOT_TOKEN = os.getenv("BOT_TOKEN")
12
13# Check that token is set
14if not BOT_TOKEN:
15    raise ValueError("BOT_TOKEN not found! Create a .env file with your token.")

 1BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

 1aiogram>=3.7.0
 2python-dotenv>=1.0.0
 3aiosqlite>=0.20.0

 1python -c "import aiogram; print(f'aiogram version: {aiogram.__version__}')"

 1my-telegram-bot/
 2├── config.py           # ✅ Created
 3├── .env                # ✅ Created (with your token)
 4├── requirements.txt    # ✅ Created
 5└── venv/               # ✅ Created (virtual environment)

 1# bot.py — main bot file
 2# Here we create the bot and register handlers
 3
 4import asyncio
 5import logging
 6from aiogram import Bot, Dispatcher, Router, F
 7from aiogram.types import Message
 8from aiogram.filters import CommandStart, Command
 9from config import BOT_TOKEN
10
11# ─── Configure logging ───
12# Shows in console what the bot is doing
13logging.basicConfig(level=logging.INFO)
14
15# ─── Create bot and dispatcher ───
16# Bot — object for sending messages
17# Dispatcher — router for incoming messages
18bot = Bot(token=BOT_TOKEN)
19dp = Dispatcher()
20
21# ─── Create router ───
22# Router groups handlers by logic
23router = Router()
24
25# ─── /start command handler ───
26# Triggered when user sends /start
27@router.message(CommandStart())
28async def cmd_start(message: Message):
29    """
30    Welcome message.
31    Shown on first contact with the bot.
32    """
33    await message.answer(
34        f"👋 Hello, <b>{message.from_user.first_name}</b>!\n\n"
35        f"I am your first Telegram bot. "
36        f"I was built in 15 minutes using this tutorial.\n\n"
37        f"Try these commands:\n"
38        f"/help — Show help\n"
39        f"/menu — Show main menu",
40        parse_mode="HTML",
41    )
42
43# ─── /help command handler ───
44@router.message(Command("help"))
45async def cmd_help(message: Message):
46    """Shows help for commands."""
47    await message.answer(
48        "📖 <b>Available Commands:</b>\n\n"
49        "/start — Restart the bot\n"
50        "/help — Show this help message\n"
51        "/menu — Show main menu\n\n"
52        "Or just type a message and I will respond!",
53        parse_mode="HTML",
54    )
55
56# ─── Handler for any text messages ───
57# Triggered on ANY text message
58@router.message(F.text)
59async def echo_message(message: Message):
60    """
61    Echo reply to text messages.
62    Shows that the bot received and processed the message.
63    """
64    await message.answer(
65        f"🔄 You said: <i>{message.text}</i>\n\n"
66        f"I received your message! In a real bot, "
67        f"this is where you would add your business logic.",
68        parse_mode="HTML",
69    )
70
71# ─── Main function ───
72async def main():
73    """
74    Entry point. Register routers and start polling.
75    Polling = bot polls Telegram for new messages.
76    """
77    # Connect router to dispatcher
78    dp.include_router(router)
79
80    # Remove webhooks (in case bot was previously running)
81    await bot.delete_webhook(drop_pending_updates=True)
82
83    # Start polling — bot begins receiving messages
84    print("🤖 Bot is running! Press Ctrl+C to stop.")
85    await dp.start_polling(bot)
86
87# ─── Launch ───
88if __name__ == "__main__":
89    asyncio.run(main())

 1python bot.py

 1# handlers.py — handlers with inline keyboards
 2# Shows how to create interactive buttons
 3
 4from aiogram import Router, F
 5from aiogram.types import (
 6    Message,
 7    CallbackQuery,
 8    InlineKeyboardButton,
 9    InlineKeyboardMarkup,
10)
11from aiogram.utils.keyboard import InlineKeyboardBuilder
12from aiogram.filters import Command
13
14router = Router()
15
16# ─── /menu command — main menu with buttons ───
17@router.message(Command("menu"))
18async def show_menu(message: Message):
19    """
20    Shows main menu with inline buttons.
21    Each button has callback_data — a string,
22    the bot receives on click.
23    """
24    # Create keyboard via Builder (convenient method)
25    builder = InlineKeyboardBuilder()
26
27    # Add buttons (one per row)
28    builder.row(
29        InlineKeyboardButton(
30            text="🍕 Food Menu",
31            callback_data="menu:food"
32        ),
33    )
34    builder.row(
35        InlineKeyboardButton(
36            text="📍 Our Location",
37            callback_data="menu:location"
38        ),
39    )
40    builder.row(
41        InlineKeyboardButton(
42            text="📞 Contact Us",
43            callback_data="menu:contact"
44        ),
45    )
46    builder.row(
47        InlineKeyboardButton(
48            text="❓ FAQ",
49            callback_data="menu:faq"
50        ),
51    )
52
53    # Send message with keyboard
54    await message.answer(
55        "📋 <b>Main Menu</b>\n\n"
56        "Choose an option below:",
57        reply_markup=builder.as_markup(),
58        parse_mode="HTML",
59    )
60
61# ─── Button press handler ───
62# Triggered when user presses an inline button
63@router.callback_query(F.data.startswith("menu:"))
64async def handle_menu_callback(callback: CallbackQuery):
65    """
66    Handles main menu button presses.
67    F.data.startswith("menu:") filters only menu buttons.
68    """
69    # Extract action from callback_data
70    action = callback.data.split(":")[1]
71
72    # Handle each action
73    if action == "food":
74        await callback.message.edit_text(
75            "🍕 <b>Food Menu</b>\n\n"
76            "• Margherita Pizza — $12\n"
77            "• Pepperoni Pizza — $14\n"
78            "• Caesar Salad — $9\n"
79            "• Pasta Carbonara — $13\n\n"
80            "Tap an item to order:",
81            reply_markup=InlineKeyboardMarkup(inline_keyboard=[
82                [InlineKeyboardButton(
83                    text="🍕 Margherita — $12",
84                    callback_data="order:margherita"
85                )],
86                [InlineKeyboardButton(
87                    text="🍕 Pepperoni — $14",
88                    callback_data="order:pepperoni"
89                )],
90                [InlineKeyboardButton(
91                    text="🥗 Caesar Salad — $9",
92                    callback_data="order:caesar"
93                )],
94                [InlineKeyboardButton(
95                    text="🔙 Back to Menu",
96                    callback_data="back:main"
97                )],
98            ]),
99            parse_mode="HTML",
100        )
101
102    elif action == "location":
103        await callback.message.edit_text(
104            "📍 <b>Our Location</b>\n\n"
105            "123 Main Street, Suite 100\n"
106            "New York, NY 10001\n\n"
107            "🕐 Hours: Mon-Fri 9am-6pm",
108            reply_markup=InlineKeyboardMarkup(inline_keyboard=[
109                [InlineKeyboardButton(
110                    text="🔙 Back to Menu",
111                    callback_data="back:main"
112                )],
113            ]),
114            parse_mode="HTML",
115        )
116
117    elif action == "contact":
118        await callback.message.edit_text(
119            "📞 <b>Contact Us</b>\n\n"
120            "Email: hello@example.com\n"
121            "Phone: (555) 123-4567\n"
122            "Telegram: @your_support_bot",
123            reply_markup=InlineKeyboardMarkup(inline_keyboard=[
124                [InlineKeyboardButton(
125                    text="🔙 Back to Menu",
126                    callback_data="back:main"
127                )],
128            ]),
129            parse_mode="HTML",
130        )
131
132    elif action == "faq":
133        await callback.message.edit_text(
134            "❓ <b>Frequently Asked Questions</b>\n\n"
135            "<b>Q: What are your hours?</b>\n"
136            "A: Mon-Fri, 9am-6pm EST.\n\n"
137            "<b>Q: Do you deliver?</b>\n"
138            "A: Yes, within Manhattan. Free over $30.\n\n"
139            "<b>Q: How do I pay?</b>\n"
140            "A: We accept all major credit cards.",
141            reply_markup=InlineKeyboardMarkup(inline_keyboard=[
142                [InlineKeyboardButton(
143                    text="🔙 Back to Menu",
144                    callback_data="back:main"
145                )],
146            ]),
147            parse_mode="HTML",
148        )
149
150    # Answer callback (remove loading indicator)
151    await callback.answer()
152
153# ─── "Back" button handler ───
154@router.callback_query(F.data == "back:main")
155async def handle_back(callback: CallbackQuery):
156    """Returns user to main menu."""
157    builder = InlineKeyboardBuilder()
158    builder.row(
159        InlineKeyboardButton(text="🍕 Food Menu", callback_data="menu:food"),
160    )
161    builder.row(
162        InlineKeyboardButton(text="📍 Our Location", callback_data="menu:location"),
163    )
164    builder.row(
165        InlineKeyboardButton(text="📞 Contact Us", callback_data="menu:contact"),
166    )
167    builder.row(
168        InlineKeyboardButton(text="❓ FAQ", callback_data="menu:faq"),
169    )
170
171    await callback.message.edit_text(
172        "📋 <b>Main Menu</b>\n\nChoose an option below:",
173        reply_markup=builder.as_markup(),
174        parse_mode="HTML",
175    )
176    await callback.answer()
177
178# ─── Order handler ───
179@router.callback_query(F.data.startswith("order:"))
180async def handle_order(callback: CallbackQuery):
181    """Handles product selection."""
182    item = callback.data.split(":")[1]
183
184    item_names = {
185        "margherita": "Margherita Pizza ($12)",
186        "pepperoni": "Pepperoni Pizza ($14)",
187        "caesar": "Caesar Salad ($9)",
188    }
189
190    item_name = item_names.get(item, item)
191
192    await callback.message.edit_text(
193        f"✅ <b>Order Confirmed!</b>\n\n"
194        f"You selected: {item_name}\n\n"
195        f"In a real bot, this would:\n"
196        f"• Save to database\n"
197        f"• Process payment\n"
198        f"• Send confirmation",
199        reply_markup=InlineKeyboardMarkup(inline_keyboard=[
200            [InlineKeyboardButton(
201                text="🔙 Back to Menu",
202                callback_data="back:main"
203            )],
204        ]),
205        parse_mode="HTML",
206    )
207    await callback.answer("Order placed! 🎉")

 1# In bot.py, add import and registration:
 2from handlers import router as handlers_router
 3
 4# In the main() function:
 5dp.include_router(handlers_router)

 1python bot.py

 1# database.py — SQLite database operations
 2# Stores users and their data
 3
 4import aiosqlite
 5from datetime import datetime
 6
 7# Path to database file
 8DB_PATH = "bot_database.db"
 9
10async def init_db():
11    """
12    Initializes the database. Creates tables if they don't exist.
13    Called once at bot startup.
14    """
15    async with aiosqlite.connect(DB_PATH) as db:
16        # Users table
17        await db.execute("""
18            CREATE TABLE IF NOT EXISTS users (
19                user_id INTEGER PRIMARY KEY,
20                username TEXT,
21                first_name TEXT,
22                last_name TEXT,
23                registered_at TEXT,
24                last_active TEXT,
25                menu_clicks INTEGER DEFAULT 0
26            )
27        """)
28
29        # Orders table (example)
30        await db.execute("""
31            CREATE TABLE IF NOT EXISTS orders (
32                id INTEGER PRIMARY KEY AUTOINCREMENT,
33                user_id INTEGER,
34                item TEXT,
35                price REAL,
36                created_at TEXT,
37                FOREIGN KEY (user_id) REFERENCES users(user_id)
38            )
39        """)
40
41        await db.commit()
42        print("✅ Database initialized successfully")
43
44async def add_user(user_id: int, username: str, first_name: str, last_name: str):
45    """
46    Adds user to database. If user already exists — updates last_active.
47    """
48    now = datetime.utcnow().isoformat()
49
50    async with aiosqlite.connect(DB_PATH) as db:
51        await db.execute("""
52            INSERT INTO users (user_id, username, first_name, last_name, registered_at, last_active)
53            VALUES (?, ?, ?, ?, ?, ?)
54            ON CONFLICT(user_id) DO UPDATE SET
55                last_active = excluded.last_active,
56                username = excluded.username
57        """, (user_id, username, first_name, last_name, now, now))
58        await db.commit()
59
60async def get_user(user_id: int) -> dict | None:
61    """
62    Gets user from database. Returns a dict with data or None.
63    """
64    async with aiosqlite.connect(DB_PATH) as db:
65        db.row_factory = aiosqlite.Row
66        cursor = await db.execute(
67            "SELECT * FROM users WHERE user_id = ?", (user_id,)
68        )
69        row = await cursor.fetchone()
70        if row:
71            return dict(row)
72        return None
73
74async def increment_menu_clicks(user_id: int):
75    """Increments menu click counter."""
76    async with aiosqlite.connect(DB_PATH) as db:
77        await db.execute(
78            "UPDATE users SET menu_clicks = menu_clicks + 1 WHERE user_id = ?",
79            (user_id,)
80        )
81        await db.commit()
82
83async def add_order(user_id: int, item: str, price: float):
84    """Adds order to database."""
85    now = datetime.utcnow().isoformat()
86
87    async with aiosqlite.connect(DB_PATH) as db:
88        await db.execute(
89            "INSERT INTO orders (user_id, item, price, created_at) VALUES (?, ?, ?, ?)",
90            (user_id, item, price, now)
91        )
92        await db.commit()
93
94async def get_user_orders(user_id: int) -> list[dict]:
95    """Gets all user orders."""
96    async with aiosqlite.connect(DB_PATH) as db:
97        db.row_factory = aiosqlite.Row
98        cursor = await db.execute(
99            "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC",
100            (user_id,)
101        )
102        rows = await cursor.fetchall()
103        return [dict(row) for row in rows]
104
105async def get_stats() -> dict:
106    """Gets bot statistics."""
107    async with aiosqlite.connect(DB_PATH) as db:
108        cursor = await db.execute("SELECT COUNT(*) FROM users")
109        total_users = (await cursor.fetchone())[0]
110
111        cursor = await db.execute("SELECT COUNT(*) FROM orders")
112        total_orders = (await cursor.fetchone())[0]
113
114        cursor = await db.execute("SELECT SUM(price) FROM orders")
115        total_revenue = (await cursor.fetchone())[0] or 0
116
117        return {
118            "total_users": total_users,
119            "total_orders": total_orders,
120            "total_revenue": round(total_revenue, 2),
121        }

 1# In bot.py, add import:
 2from database import init_db, add_user, get_user, increment_menu_clicks, add_order, get_user_orders, get_stats
 3
 4# In /start handler — save user:
 5@router.message(CommandStart())
 6async def cmd_start(message: Message):
 7    # Save user to database
 8    await add_user(
 9        user_id=message.from_user.id,
10        username=message.from_user.username or "",
11        first_name=message.from_user.first_name or "",
12        last_name=message.from_user.last_name or "",
13    )
14
15    await message.answer(
16        f"👋 Welcome back, <b>{message.from_user.first_name}</b>!\n\n"
17        f"I remember you from our last conversation.",
18        parse_mode="HTML",
19    )
20
21# In menu handler — count clicks:
22@router.message(Command("menu"))
23async def show_menu(message: Message):
24    await increment_menu_clicks(message.from_user.id)
25    # ... rest of menu code
26
27# In order handler — save order:
28@router.callback_query(F.data.startswith("order:"))
29async def handle_order(callback: CallbackQuery):
30    item = callback.data.split(":")[1]
31    prices = {"margherita": 12.0, "pepperoni": 14.0, "caesar": 9.0}
32    price = prices.get(item, 0)
33
34    await add_order(
35        user_id=callback.from_user.id,
36        item=item,
37        price=price,
38    )
39    # ... rest of order code
40
41# In main() function — initialize database:
42async def main():
43    await init_db()  # Create tables at startup
44    dp.include_router(router)
45    dp.include_router(handlers_router)
46    await bot.delete_webhook(drop_pending_updates=True)
47    print("🤖 Bot is running! Press Ctrl+C to stop.")
48    await dp.start_polling(bot)

 1python bot.py

 1ssh root@YOUR_SERVER_IP

 1# Update packages
 2apt update && apt upgrade -y
 3
 4# Install Python and pip
 5apt install python3 python3-pip python3-venv -y
 6
 7# Create folder for bot
 8mkdir /opt/my-telegram-bot
 9cd /opt/my-telegram-bot

 1# Copy files to server
 2scp -r ./* root@YOUR_SERVER_IP:/opt/my-telegram-bot/

 1cd /opt/my-telegram-bot
 2
 3# Create virtual environment
 4python3 -m venv venv
 5source venv/bin/activate
 6
 7# Install dependencies
 8pip install -r requirements.txt

 1# Create service file
 2cat > /etc/systemd/system/telegram-bot.service << 'EOF'
 3[Unit]
 4Description=Telegram Bot
 5After=network.target
 6
 7[Service]
 8Type=simple
 9User=root
10WorkingDirectory=/opt/my-telegram-bot
11ExecStart=/opt/my-telegram-bot/venv/bin/python bot.py
12Restart=always
13RestartSec=10
14Environment=PYTHONUNBUFFERED=1
15
16[Install]
17WantedBy=multi-user.target
18EOF
19
20# Enable and start service
21systemctl daemon-reload
22systemctl enable telegram-bot
23systemctl start telegram-bot

 1# Check status
 2systemctl status telegram-bot
 3
 4# View logs
 5journalctl -u telegram-bot -f

 1# webhook_bot.py — running bot in webhook mode
 2# Use in production instead of polling
 3
 4import asyncio
 5from aiohttp import web
 6from aiogram import Bot, Dispatcher
 7from aiogram.webhook.aiohttp_server import SimpleRequestHandler, setup_application
 8from config import BOT_TOKEN
 9
10# ─── Webhook settings ───
11WEBHOOK_HOST = "https://your-domain.com"  # Your domain with SSL
12WEBHOOK_PATH = "/webhook"                  # Webhook path
13WEBHOOK_URL = f"{WEBHOOK_HOST}{WEBHOOK_PATH}"
14
15# Path to SSL certificates (if using your own server)
16WEBAPP_HOST = "0.0.0.0"  # Listen on all interfaces
17WEBAPP_PORT = 8443        # Standard port for Telegram webhook
18
19async def on_startup(bot: Bot):
20    """
21    Called at bot startup. Sets webhook URL in Telegram.
22    """
23    await bot.set_webhook(
24        url=WEBHOOK_URL,
25        # You can specify allowed_updates if only certain types are needed
26    )
27    print(f"✅ Webhook set to: {WEBHOOK_URL}")
28
29async def on_shutdown(bot: Bot):
30    """Called at bot shutdown."""
31    await bot.delete_webhook()
32    print("❌ Webhook removed")
33
34def main():
35    # Create bot and dispatcher
36    bot = Bot(token=BOT_TOKEN)
37    dp = Dispatcher()
38
39    # Register routers (same as in polling version)
40    from handlers import router
41    dp.include_router(router)
42
43    # Register startup/shutdown hooks
44    dp.startup.register(on_startup)
45    dp.shutdown.register(on_shutdown)
46
47    # Create aiohttp application
48    app = web.Application()
49
50    # Configure webhook handler
51    webhook_requests_handler = SimpleRequestHandler(
52        dispatcher=dp,
53        bot=bot,
54    )
55    webhook_requests_handler.register(app, path=WEBHOOK_PATH)
56
57    # Connect dispatcher to application
58    setup_application(app, dp, bot=bot)
59
60    # Start web server
61    print(f"🤖 Webhook bot running on {WEBAPP_HOST}:{WEBAPP_PORT}")
62    web.run_app(app, host=WEBAPP_HOST, port=WEBAPP_PORT)
63
64if __name__ == "__main__":
65    main()

 1telegram.error.Unauthorized: Unauthorized

 1aiogram.exceptions.TelegramConflictError: Conflict: terminated by other getUpdates

 1# Find and kill all Python processes running your bot
 2# Windows:
 3taskkill /F /IM python.exe
 4
 5# macOS/Linux:
 6pkill -f bot.py
 7
 8# Then restart:
 9python bot.py

 1aiosqlite.OperationalError: database is locked

 1# In database.py, use connection pool:
 2import aiosqlite
 3
 4# Global connection (opened once)
 5_db = None
 6
 7async def get_db():
 8    """Returns global database connection."""
 9    global _db
10    if _db is None:
11        _db = await aiosqlite.connect(DB_PATH)
12    return _db
13
14async def add_user(user_id: int, username: str, first_name: str, last_name: str):
15    """Adds user (with global connection)."""
16    db = await get_db()
17    now = datetime.utcnow().isoformat()
18    await db.execute(
19        "INSERT OR REPLACE INTO users (user_id, username, first_name, last_name, last_active) "
20        "VALUES (?, ?, ?, ?, ?)",
21        (user_id, username, first_name, last_name, now)
22    )
23    await db.commit()