Как создать Telegram-бота на Python с aiogram 3: пошаговый гайд

Обновлено: июнь 2026

Telegram Bot API сейчас на версии 10.1, и это уже не просто «отправить текст в чат». Боты научились таблицам, заголовкам H1–H6, аккордеонам, стримингу и топикам. Фреймворк aiogram 3.29 поддерживает всё это из коробки. В этом гайде разберём создание бота с нуля: BotFather, handlers, FSM, Rich Messages и деплой на Railway — с рабочим кодом на каждом шаге.

TL;DR: aiogram 3.29 + Python 3.11+ = самый быстрый способ написать Telegram-бота в 2026. За пару часов можно получить рабочий бот с клавиатурами, состояниями (FSM) и задеплоить его на Railway бесплатно. Telegram Bot API 10.1 добавил Rich Messages: заголовки, таблицы, спойлеры и стриминг — всё это уже работает через answer_rich().

Что такое aiogram 3 и зачем он нужен?

aiogram 3 — это асинхронный Python-фреймворк для Telegram Bot API. Он быстрее и чище, чем синхронные альтернативы, и поддерживает все новые фичи Bot API, включая 10.1.

Если когда-то делали бота на pyTelegramBotAPI или старом aiogram 2, вы поймёте разницу примерно на третьем часу работы. Aiogram 3 перешёл на роутеры вместо одного глобального диспетчера, добавил нормальные middleware и переделал логику фильтров. Код стал читаться как обычный Python — без магии и накопленного технического долга.

На aiogram 3.29 (актуальная версия на июнь 2026) уже работают Rich Messages из Bot API 10.1. Это возможность отправлять отформатированные сообщения с заголовками, разделителями, таблицами и даже аккордеонами. Функция пока доступна только в ботах, но для многих задач это именно то, чего не хватало.

Шаг 1. Как создать бота через BotFather?

В Telegram найдите @BotFather, напишите /newbot, придумайте имя и username — получите токен. Весь процесс занимает две минуты.

Открываете Telegram, в поиске пишете @BotFather. Важно: у настоящего BotFather стоит синяя галочка верификации. Нажимаете /start, потом /newbot.

Дальше он спросит два вещи:

• Имя бота (то, что видят пользователи) — например, Мой первый бот
• Username (уникальный идентификатор) — должен заканчиваться на _bot, например my_first_vibecoderz_bot

В ответ получите токен вида 7234567890:AAH.... Это секретный ключ — никому не показывайте, в git не коммитьте.

Здесь же через BotFather стоит сразу настроить команды и описание бота. Команда /setdescription добавит текст, который пользователь увидит до старта.

Шаг 2. Как настроить проект и установить aiogram 3?

Создаём виртуальное окружение, устанавливаем aiogram через pip, кладём токен в .env. Стандартная структура — три файла: main.py, handlers.py, keyboards.py.

Структура проекта для нормального бота выглядит вот так:

my_bot/
├── .env              # токен и секреты
├── main.py           # точка входа
├── handlers/
│   └── user.py       # обработчики
├── keyboards/
│   └── reply.py      # клавиатуры
└── states.py         # FSM-состояния

Создаём виртуальное окружение и ставим зависимости:

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

# Устанавливаем aiogram
pip install aiogram python-dotenv

Создаём .env:

BOT_TOKEN=7234567890:AAH_ваш_токен_тут

И базовый main.py:

import asyncio
from aiogram import Bot, Dispatcher
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from dotenv import load_dotenv
import os

load_dotenv()
TOKEN = os.getenv("BOT_TOKEN")

async def main():
    bot = Bot(
        token=TOKEN,
        default=DefaultBotProperties(parse_mode=ParseMode.HTML)
    )
    dp = Dispatcher()
    await dp.start_polling(bot)

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

Запускаете python main.py — бот живёт, но пока молчит. Это нормально: обработчиков ещё нет.

Шаг 3. Как написать первые handlers в aiogram 3?

Handler — функция, которая срабатывает на определённое событие: сообщение, команду, нажатие кнопки. В aiogram 3 они подключаются через роутер, а не диспетчер напрямую.

Создаём handlers/user.py:

from aiogram import Router, F
from aiogram.types import Message
from aiogram.filters import CommandStart, Command

router = Router()

@router.message(CommandStart())
async def cmd_start(message: Message):
    await message.answer(
        f"Привет, {message.from_user.first_name}! 👋\n"
        "Я бот на aiogram 3. Напиши что-нибудь."
    )

@router.message(Command("help"))
async def cmd_help(message: Message):
    await message.answer("Доступные команды:\n/start — начало\n/help — помощь")

@router.message(F.text)
async def echo(message: Message):
    await message.answer(f"Ты написал: {message.text}")

Подключаем роутер в main.py:

from handlers.user import router as user_router

# Внутри функции main(), до start_polling:
dp.include_router(user_router)

Порядок важен: обработчик /start должен быть выше эхо-обработчика. Aiogram проверяет хендлеры сверху вниз и останавливается на первом совпадении.

Из транскрипций видео по aiogram, которые мы анализировали, хорошо видно типичную ошибку новичков: ставить общий F.text обработчик выше команд. Тогда /start никогда не сработает — всё поймает эхо.

Шаг 4. Как сделать клавиатуры Reply и Inline?

Reply-клавиатура появляется вместо стандартной, Inline — прямо под сообщением. Первая — для навигации, вторая — для действий с конкретным контентом.

Reply-клавиатура (она же кнопки под полем ввода):

from aiogram.types import ReplyKeyboardMarkup, KeyboardButton

def get_main_keyboard():
    kb = ReplyKeyboardMarkup(
        keyboard=[
            [KeyboardButton(text="Каталог"), KeyboardButton(text="Поиск")],
            [KeyboardButton(text="Помощь")]
        ],
        resize_keyboard=True,
        input_field_placeholder="Выберите раздел"
    )
    return kb

Inline-клавиатура (кнопки под конкретным сообщением):

from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton

def get_category_keyboard():
    kb = InlineKeyboardMarkup(inline_keyboard=[
        [
            InlineKeyboardButton(text="Cursor", callback_data="tool_cursor"),
            InlineKeyboardButton(text="Windsurf", callback_data="tool_windsurf")
        ],
        [InlineKeyboardButton(text="Посмотреть всё", url="https://vibecoderz.ru/ide")]
    ])
    return kb

Обработчик нажатия на Inline-кнопку:

from aiogram.types import CallbackQuery

@router.callback_query(F.data.startswith("tool_"))
async def process_tool(callback: CallbackQuery):
    tool_name = callback.data.split("_")[1]
    await callback.message.answer(f"Вы выбрали: {tool_name.capitalize()}")
    await callback.answer()  # убирает «часики» с кнопки

callback.answer() в конце обязателен. Без него кнопка будет «крутиться» у пользователя несколько секунд.

Шаг 5. Что такое FSM и как им пользоваться?

FSM (Finite State Machine) — способ вести «диалог» с пользователем через несколько шагов. Бот запоминает, на каком этапе находится каждый пользователь, и реагирует соответственно.

Без FSM бот не понимает контекст. Пользователь пишет «Максим» — и что? Это имя, ответ на вопрос или случайное сообщение? FSM позволяет задать вопрос и ждать конкретного ответа.

Пример: форма регистрации с именем и номером телефона.

# states.py
from aiogram.fsm.state import State, StatesGroup

class RegistrationStates(StatesGroup):
    waiting_name = State()
    waiting_phone = State()

# В handlers/user.py добавляем:
from aiogram.fsm.context import FSMContext
from aiogram.types import ReplyKeyboardRemove, KeyboardButton
from states import RegistrationStates

@router.message(CommandStart())
async def cmd_start(message: Message, state: FSMContext):
    await message.answer(
        "Как вас зовут?",
        reply_markup=ReplyKeyboardRemove()
    )
    await state.set_state(RegistrationStates.waiting_name)

@router.message(RegistrationStates.waiting_name, F.text)
async def process_name(message: Message, state: FSMContext):
    await state.update_data(name=message.text)

    phone_kb = ReplyKeyboardMarkup(
        keyboard=[[KeyboardButton(text="Отправить номер", request_contact=True)]],
        resize_keyboard=True
    )
    await message.answer("Отправьте ваш номер телефона:", reply_markup=phone_kb)
    await state.set_state(RegistrationStates.waiting_phone)

@router.message(RegistrationStates.waiting_phone, F.contact)
async def process_phone(message: Message, state: FSMContext):
    data = await state.get_data()
    name = data.get("name")
    phone = message.contact.phone_number

    await message.answer(
        f"Готово! Имя: {name}, телефон: {phone}",
        reply_markup=get_main_keyboard()
    )
    await state.clear()

Важный момент: данные FSM хранятся в оперативной памяти по умолчанию. Если бот перезапустится, состояния сбросятся. Для продакшена используют RedisStorage или MongoStorage.

Максим: «GoBanana мы собрали за 6–8 часов суммарно — и именно FSM сделал возможным пошаговый флоу выбора стиля фото. Без состояний бот не понимает, на каком этапе пользователь. У нас 200 000+ юзеров прошли этот флоу без единого бага в логике состояний.»

Что такое Rich Messages в Bot API 10.1?

Bot API 10.1 добавил форматированные сообщения (Rich Messages) с заголовками H1–H6, таблицами, спойлерами и аккордеонами. Отправляются через answer_rich() вместо обычного answer().

Это главное нововведение, которое пришло в aiogram 3.29. Раньше у ботов были только жирный текст, курсив и код-блоки. Теперь можно делать настоящие статьи прямо в чате.

Пример отправки Rich Message через HTML:

from aiogram.types import Message, InputRichMessage

@router.message(Command("rich_demo"))
async def send_rich(message: Message):
    html_content = """
<h1>Обзор инструментов вайбкодинга</h1>
<hr/>
<h2>AI IDE</h2>
<p>Три лидера рынка на июнь 2026:</p>
<table>
  <tr><th>Инструмент</th><th>Цена</th><th>Особенность</th></tr>
  <tr><td>Cursor</td><td>$20/мес</td><td>Лучший таббинг</td></tr>
  <tr><td>Windsurf</td><td>$15/мес</td><td>Cascade-агент</td></tr>
  <tr><td>Claude Code</td><td>по токенам</td><td>SWE-bench 88.6%</td></tr>
</table>
<details>
<summary>Подробнее о Claude Code</summary>
<p>Claude Code работает в терминале. Claude Opus 4.8 — #3 в SWE-bench Verified.</p>
</details>
"""
    rich_msg = InputRichMessage(html=html_content)
    await message.answer_rich(rich_msg)

Важный нюанс из транскрипций: Rich Messages пока работают только в личных сообщениях с ботом. В каналах и группах функция недоступна — Telegram ещё не добавил редактор для таких форматов на своей стороне.

Что поддерживает Bot API 10.1 в Rich Messages:

• Заголовки H1–H6
• Разделитель <hr/>
• Таблицы <table> со стилизованным хедером
• Спойлеры <tg-spoiler>
• Выделение <mark> (текст с цветным фоном)
• Раскрывающиеся блоки <details> / <summary> (аккордеон)
• Блочные цитаты и «футер»
• Стриминг через send_rich_message_draft

Шаг 6. Как задеплоить бота на Railway?

Railway — проще всего для старта. Подключаете GitHub-репозиторий, добавляете переменную BOT_TOKEN, нажимаете Deploy. Бот живёт в облаке без вашего компьютера.

Деплой на Railway занимает примерно 10 минут. Вот порядок:

1. Создайте requirements.txt:

aiogram==3.29.0
python-dotenv==1.0.0

1. Создайте Procfile:

worker: python main.py

1. Создайте репозиторий на GitHub и загрузите код (без .env — он в .gitignore).
2. Зайдите на railway.app, создайте новый проект, выберите «Deploy from GitHub repo».
3. В разделе Variables добавьте:

BOT_TOKEN=ваш_токен_из_botfather

1. Railway автоматически поднимет деплой. В логах увидите запуск поллинга.

Бесплатный план Railway даёт $5 кредитов в месяц. Для простого бота этого хватает. Если нужен более серьёзный хостинг, смотрите на Replit или VPS на Ubuntu с Docker.

Как устроен стриминг в Bot API 10.1?

Стриминг — отправка сообщения по частям, как будто бот «печатает» в реальном времени. Используется метод send_rich_message_draft. Пока есть проблемы с rate limits, но функция уже рабочая.

Из транскрипций видео видно реальный опыт разработчиков: при задержке в 0.2 секунды между чанками Telegram всё равно выдаёт rate limit. Это не баг aiogram — это ограничение на стороне Telegram. В документации Bot API это не описано, но разработчики уже работают над решением.

Рабочий пример стриминга с обработкой rate limit:

import asyncio
from aiogram.exceptions import TelegramRetryAfter

@router.message(F.text & ~F.text.startswith("/"))
async def stream_response(message: Message, state: FSMContext):
    # Проверяем, что пользователь не ожидает уже
    current_state = await state.get_state()
    if current_state == "processing":
        await message.answer("Подождите, обрабатываю запрос...")
        return

    await state.set_state("processing")
    draft_id = message.message_id
    full_text = ""

    # Симуляция стриминга (замените на реальный AI)
    chunks = ["Привет! ", "Это ", "стриминг ", "в Telegram!"]

    for chunk in chunks:
        full_text += chunk
        try:
            await message.bot.send_rich_message_draft(
                chat_id=message.chat.id,
                draft_id=draft_id,
                text=full_text,
                message_thread_id=message.message_thread_id  # важно для топиков
            )
            await asyncio.sleep(0.3)
        except TelegramRetryAfter as e:
            await asyncio.sleep(e.retry_after)

    # Финальное сообщение
    await message.answer(full_text)
    await state.clear()

message_thread_id здесь критически важен. Без него ответ улетит не в тот топик — это частая ошибка, которую сложно отловить в тестах.

Как избежать типичных ошибок при работе с telegram api python?

Пять ошибок, которые делают почти все: неправильный порядок хендлеров, забытый callback.answer(), состояния без хранилища, токен в коде, и отсутствие обработки исключений.

1. Порядок хендлеров. Aiogram проверяет обработчики сверху вниз. Если F.text стоит выше CommandStart(), команда /start никогда не сработает. Специфичные фильтры всегда выше общих.

2. Забытый callback.answer(). После обработки нажатия на Inline-кнопку обязательно вызывайте этот метод. Без него кнопка «зависает» у пользователя на несколько секунд с анимацией загрузки.

3. FSM без Redis в продакшене. Дефолтное хранилище — память процесса. После перезапуска бота все состояния сбрасываются. Пользователи, которые были в середине регистрации, получают «что?» вместо следующего шага.

4. Токен в коде. Никогда не пишите токен прямо в файле. Только через переменные окружения и .env. .envобязательно в .gitignore.

5. Отсутствие логирования. При ошибках без логов вы просто не поймёте, что произошло. Минимальный setup:

import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

Сравнение aiogram 3 и python-telegram-bot в 2026

aiogram 3 быстрее за счёт полной асинхронности. python-telegram-bot проще для новичков. Для продакшена с нагрузкой — aiogram, для первого бота — оба подойдут.

Если вы создаёте бота для внутреннего инструмента или автоматизации — оба варианта рабочие. Если цель — продакшен-бот с тысячами пользователей и богатым UI через Rich Messages — aiogram 3.29 будет лучшим выбором на сейчас.

Для ускорения разработки ботов стоит посмотреть на Claude Code — он отлично понимает asyncio и aiogram, генерирует handlers и FSM-состояния с правильной структурой. На Cursor удобно рефакторить существующий код бота с автодополнением.

FAQ

Нужно ли знать Python для создания Telegram-бота на aiogram 3? Базовые знания Python нужны: переменные, функции, циклы, классы. Asyncio на старте можно не понимать глубоко — достаточно писать async def и await. Большую часть шаблонного кода сегодня генерирует AI по вашему описанию.

Что такое polling и когда использовать webhook? Polling — ваш бот сам каждые N секунд спрашивает Telegram «есть новые сообщения?». Webhook — Telegram сам отправляет обновления на ваш URL. Для разработки polling проще. Для продакшена с высокой нагрузкой webhook быстрее и экономит ресурсы.

Как подключить базу данных к Telegram-боту? Для простых случаев — SQLite через aiosqlite. Для продакшена — PostgreSQL через asyncpg или SQLAlchemy с асинхронным движком. Redis подходит для хранения FSM-состояний и кэша. ORM типа SQLAlchemy упрощает работу со схемами.

Можно ли сделать бота с AI (ChatGPT, Claude) через aiogram? Да, и это стандартный сценарий. Подключаете OpenAI или Anthropic SDK, в хендлере делаете запрос к API, возвращаете ответ пользователю. С Bot API 10.1 можно добавить стриминг через send_rich_message_draft — ответ появляется по частям, как в ChatGPT.

Как aiogram работает с Telegram Bot API 10.1 и Rich Messages? В aiogram 3.29 появился метод answer_rich(), который принимает InputRichMessage. Внутри можно использовать HTML с тегами <h1>–<h6>, <table>, <details>, <tg-spoiler>, <mark> и другими. Функция пока только для личных сообщений с ботом.

Что лучше для деплоя бота в 2026: Railway или VPS? Railway — для старта и небольших ботов. Просто, дешево, GitHub-интеграция из коробки. VPS (Hetzner, DigitalOcean) — если нужен контроль, база данных на том же сервере или Docker-композ с несколькими сервисами. Replit — для быстрого прототипирования, но засыпает на бесплатном плане.

Сколько времени нужно, чтобы написать первого бота? Простой эхо-бот с командой /start — 30 минут. Бот с клавиатурами, FSM-регистрацией и деплоем на Railway — 3–4 часа. Бот с подключённым AI, базой данных и Rich Messages — день-два. Вайбкодинг через Claude Code или Cursor ускоряет всё это примерно в 3 раза.

Глоссарий

aiogram — асинхронный Python-фреймворк для Telegram Bot API. Версия 3.x полностью переработана по сравнению с 2.x.

Bot API — HTTP API от Telegram для взаимодействия с ботами. Текущая версия: 10.1 (июнь 2026).

BotFather — официальный бот Telegram для создания и управления ботами. Username: @BotFather.

Dispatcher (dp) — центральный объект aiogram, распределяет входящие обновления по роутерам и хендлерам.

FSM (Finite State Machine) — конечный автомат состояний. Позволяет боту вести многошаговые диалоги, запоминая, на каком этапе находится каждый пользователь.

Handler — функция-обработчик, которая срабатывает на определённое событие (сообщение, callback, команда).

Inline-клавиатура — кнопки, прикреплённые к конкретному сообщению. Нажатие генерирует CallbackQuery.

Polling — режим работы бота, при котором он регулярно запрашивает обновления у Telegram API.

Reply-клавиатура — кнопки, которые заменяют стандартную клавиатуру пользователя.

Rich Messages — новый формат сообщений в Bot API 10.1 с поддержкой заголовков, таблиц, спойлеров и аккордеонов.

Router — модуль aiogram 3 для группировки хендлеров. Заменил концепцию одного глобального диспетчера.

Webhook — способ получения обновлений, при котором Telegram сам отправляет данные на ваш URL.

Если хотите разобраться с конкретным инструментом для разработки ботов, загляните в наш каталог AI-инструментов — там есть обзоры Cursor, Windsurf, Claude Code и других IDE, которые ускоряют написание кода.

Есть вопросы по архитектуре бота или выбору стека? Запишитесь на консультацию к Максиму — разберём вашу задачу и подберём оптимальный подход.

Обновлено: июнь 2026. Данные актуальны для aiogram 3.29 и Telegram Bot API 10.1.