VibeCoderzVibeCoderz
Все статьи
Вайбкодинг: гайды2026/06/249 мин чтения

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

С помощью aiogram 3.29 и Python 3.11+ вы сможете за пару часов собрать Telegram‑бота с клавиатурами, состояниями и Rich‑Message‑поддержкой, а затем развернуть его бесплатно на Railway.

Содержание (12)+

Обновлено: октябрь 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. Это возможность отправлять отформатированные сообщения с заголовками, разделителями, таблицами и даже аккордеонами. Функция пока доступна только в ботах, но для многих задач это именно то, чего не хватало.

Критерийaiogram 2aiogram 3.29
АсинхронностьЧастичнаяПолная (asyncio)
АрхитектураОдин диспетчерРоутеры (Router)
MiddlewareСложныеПростые декораторы
Bot API 10.1НетДа
Rich MessagesНетДа (answer_rich)
FSM хранилищеВ памятиПамять / Redis / MongoDB
Изображение

Шаг 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() в конце обязателен. Без него кнопка будет «крутиться» у пользователя несколько секунд.

Изображение
Тип клавиатурыГде появляетсяКогда использовать
ReplyKeyboardMarkupВместо стандартной клавиатурыОсновная навигация, постоянное меню
InlineKeyboardMarkupПод конкретным сообщениемДействия с объектом, пагинация, выбор
ReplyKeyboardRemoveУбирает reply-клавиатуруПри старте FSM-опроса

Шаг 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.

ПлатформаЦенаПлюсыМинусы
Railway$5 кредитов/мес бесплатноПросто, GitHub-интеграцияЛимит ресурсов
ReplitБесплатный тирБраузерная IDEЗасыпает при неактивности
VPS (Hetzner)от €4/месПолный контрольНужна настройка
Docker + Railway$5+ВоспроизводимоСложнее старт

Как устроен стриминг в 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, для первого бота — оба подойдут.

Параметрaiogram 3.29python-telegram-bot 21
АсинхронностьПолнаяПолная (с v20)
Bot API 10.1ДаЧастично
Rich MessagesДаНет (июнь 2026)
Кривая обученияСредняяНизкая
ДокументацияХорошаяОтличная
ПроизводительностьВышеНемного ниже
СообществоАктивноеОчень большое

Если вы создаёте бота для внутреннего инструмента или автоматизации — оба варианта рабочие. Если цель — продакшен-бот с тысячами пользователей и богатым 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 раза.



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

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


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

Автор

Максим Наговицын

Маркетинг-стратег, IT-предприниматель, ментор по вайбкодингу

2026/06/24

10+ лет в маркетинге, 300+ клиентских проектов: сайты, реклама, боты. Создатель GoBanana (228K+ пользователей, 11.6 млн ₽ выручки) и VibeCoderz. Делаю AI-продукты сам через Claude Code, Cursor, Windsurf и консультирую тех, кто хочет так же.

Об авторе →
All Posts

Инструменты, упомянутые в статье

Читать далее

📄 Статья

Миграции базы данных для новичка: как менять схему без потери данных

Миграции базы данных — это версионированные скрипты, которые переводят схему БД из одного состояния в другое без ручных правок и без потери данных. Разберем, зачем они нужны, чем отличаются Alembic, Drizzle и Prisma migrate, и что делать, если миграц…

2026/10/0610 мин
📄 Статья

Память AI-агента 2026 как перестать забывать диалоги

Память AI-агента - это отдельный сервис за пределами разговора, который хранит факты о пользователе, о себе и о мире между сессиями. Контекстное окно решает только половину задачи: пока диалог помещается в лимит токенов, модель помнит все детали, а с…

2026/09/089 мин
📄 Статья

Автоматическая проверка кода 2026 три уровня защиты в CI

Автоматическая проверка кода в 2026 году строится не на одном инструменте, а на трех слоях, которые ловят разные типы проблем: линтер следит за стилем и синтаксисом, статический анализ ищет уязвимости и логические ошибки, AI-ревью оценивает архитекту…

2026/09/0812 мин
📄 Статья

Мониторинг AI агентов 2026 логи алерты трейсинг

Мониторинг AI агентов в 2026 году строится на трех слоях: логирование каждого шага, трейсинг вызовов инструментов и алерты при отклонениях. Без этого агент работает как черный ящик, а первый сигнал проблемы приходит от клиента в саппорт, а не от сист…

2026/09/0411 мин
📄 Статья

Авторизация для AI-продуктов 2026 Clerk Auth0 или Supabase Auth

Clerk, Auth0 и Supabase Auth решают одну задачу: пускать пользователя в приложение и запоминать, кто он такой. Для большинства AI-продуктов на вайбкодинге короче и дешевле берется Clerk с готовым UI логина, Supabase Auth подходит, если база данных уж…

2026/09/049 мин
📄 Статья

AI-агент с долгосрочной памятью 2026 как это работает

Большинство чат-ботов и агентов сегодня работают как золотая рыбка. Закрыл диалог, и агент забыл, что вы веган, что вас зовут Игорь и что вчера уже объясняли ему задачу трижды. Long-term memory агента решает эту проблему: она хранит факты о пользоват…

2026/09/049 мин