Телеграм-бот на Python за вечер: пошаговая инструкция

За два-три часа вы получите работающего телеграм-бота: он отзовётся на команду /start, ответит на текстовые сообщения и покажет кнопки. Писать будем на Python 3.11 и библиотеке aiogram 3.x — это актуальная ветка, синтаксис которой заметно отличается от старой 2.x, поэтому примеры из чужих гайдов двухлетней давности у вас могут не запуститься. Здесь всё под 3.x.

Что нужно иметь до начала

• Python 3.10 или новее. Проверьте: python --version (на некоторых системах — python3 --version). aiogram 3.x требует минимум 3.8, но берите 3.10+.
• Установленный pip — идёт вместе с Python.
• Аккаунт в Telegram и приложение, где вы сможете открыть чат с ботом.
• Любой редактор кода: VS Code, PyCharm или хоть Блокнот.

Доступ к серверу не нужен — на этом этапе бот запускается прямо на вашем компьютере через long polling, то есть сам опрашивает Telegram. Внешний IP и домен не требуются.

Шаг 1. Получить токен у BotFather

1. Откройте в Telegram чат с @BotFather — это официальный бот для создания ботов.
2. Отправьте команду /newbot.
3. Введите отображаемое имя бота (любое) и затем username — он должен заканчиваться на bot, например my_evening_bot.
4. BotFather пришлёт строку вида 123456789:AAH... — это токен.

Проверка: вы видите сообщение «Done! Congratulations...» и в нём токен. Скопируйте его и никому не показывайте — по токену любой сможет управлять ботом.

Шаг 2. Поставить aiogram в изолированное окружение

Создайте папку проекта и виртуальное окружение, чтобы не засорять систему.

# создаём и активируем виртуальное окружение
python -m venv venv

# активация в Windows (PowerShell):
venv\Scripts\Activate.ps1
# активация в macOS/Linux:
source venv/bin/activate

# ставим aiogram версии 3.x
pip install "aiogram>=3.0,<4.0"

Проверка: команда pip show aiogram покажет установленную версию, и она начинается с 3.

Шаг 3. Минимальный бот, который отвечает на /start

Создайте файл bot.py. Токен не вписывайте в код напрямую — прочитайте его из переменной окружения, чтобы случайно не выложить в git.

import asyncio
import os
import logging

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

# токен читаем из переменной окружения BOT_TOKEN
TOKEN = os.getenv("BOT_TOKEN")

logging.basicConfig(level=logging.INFO)

dp = Dispatcher()


# хендлер команды /start
@dp.message(CommandStart())
async def on_start(message: Message):
    await message.answer("Привет! Я работаю. Напишите мне что-нибудь.")


# хендлер любого текстового сообщения — эхо
@dp.message()
async def echo(message: Message):
    await message.answer(f"Вы написали: {message.text}")


async def main():
    bot = Bot(token=TOKEN)
    # снимаем накопившиеся апдейты и запускаем опрос
    await bot.delete_webhook(drop_pending_updates=True)
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Задайте токен в той же сессии терминала, где будете запускать бота:

# macOS/Linux
export BOT_TOKEN="123456789:AAH..."

# Windows PowerShell
$env:BOT_TOKEN = "123456789:AAH..."

Запустите:

python bot.py

Проверка: в терминале появятся строки логов уровня INFO про запуск polling. Откройте чат с ботом, отправьте /start — он ответит приветствием. Напишите любой текст — вернёт «Вы написали: ...».

Одно предложение про порядок хендлеров

aiogram проверяет хендлеры сверху вниз и берёт первый подходящий, поэтому echo с пустым фильтром стоит объявлять последним — иначе он перехватит и команды тоже.

Шаг 4. Добавить кнопки

Дадим пользователю две кнопки под полем ввода. Добавьте импорт и новый хендлер.

from aiogram.types import ReplyKeyboardMarkup, KeyboardButton
from aiogram.filters import Command


@dp.message(Command("menu"))
async def show_menu(message: Message):
    keyboard = ReplyKeyboardMarkup(
        keyboard=[
            [KeyboardButton(text="Помощь"), KeyboardButton(text="О боте")],
        ],
        resize_keyboard=True,  # кнопки подгоняются под размер
    )
    await message.answer("Выберите пункт:", reply_markup=keyboard)

Разместите этот хендлер выше эхо-хендлера. Нажатия на кнопки приходят как обычные текстовые сообщения — их можно ловить по тексту:

from aiogram import F  # объект для фильтров по содержимому


@dp.message(F.text == "Помощь")
async def on_help(message: Message):
    await message.answer("Команды: /start, /menu")

Проверка: отправьте /menu — появятся две кнопки. Нажмите «Помощь» — бот ответит списком команд.

Кнопки в Telegram бывают двух типов: reply-клавиатура заменяет поле ввода и шлёт обычный текст, а inline-кнопки прикреплены к сообщению и шлют callback. Для первого вечера хватает reply — с ней не нужно обрабатывать отдельный тип апдейта.

Если не получилось

• TelegramUnauthorizedError / Unauthorized — токен неверный или не подставился. Проверьте, что переменная BOT_TOKEN задана в том же окне терминала, откуда запускаете python bot.py.
• ModuleNotFoundError: No module named 'aiogram' — окружение не активировано или библиотека не установлена. Активируйте venv и повторите pip install.
• TypeError про Bot(...) или неизвестный аргумент — почти всегда это код от aiogram 2.x, где синтаксис другой. Сверьтесь с примером выше и с документацией 3.x.
• Бот запущен, но не отвечает — проверьте, что вы пишете именно тому боту, чей токен взяли, и что процесс python bot.py не упал (в терминале нет трейсбека).
• terminated by other getUpdates request — вы запустили две копии бота одновременно. Telegram не даёт двум процессам опрашивать один токен. Остановите лишний.

Быстрая шпаргалка по объектам aiogram 3.x

Что делать дальше

Пока бот живёт, только пока открыт терминал. Следующий шаг — вынести токен в файл .env и читать его через библиотеку вроде python-dotenv, а сам .env добавить в .gitignore. Дальше — деплой: на постоянную работу бота переводят либо на VPS под управлением systemd, либо переключают с polling на webhook. Хранение данных пользователей и состояний диалога (FSM) в aiogram — отдельная большая тема, здесь мы её не трогали.