Telegram Lead Bot

О проекте

Telegram Lead Bot — продуктовая реализация Telegram-бота для сбора заявок и контактов от потенциальных клиентов.

Проект собран на базе переиспользуемого Telegram Bot Template и показывает, как из общей платформенной основы можно собрать конкретный коммерческий сценарий: пользователь читает информацию об услуге, оставляет контакт и отправляет заявку, а администратор получает и обрабатывает лиды.

Это не универсальный framework для любых Telegram-ботов, а прикладной lead-generation продукт, который можно адаптировать под разные ниши:

• юрист
• психолог
• риелтор
• консультант
• экспертные услуги
• малый бизнес, которому нужны заявки из Telegram

Моя роль

Проект разработан в формате AI-assisted development.

Я отвечал за постановку задачи, проектирование пользовательского сценария сбора заявок и админского сценария обработки лидов, проверку архитектурных решений, запуск проекта, анализ ошибок и логов, отладку, тестирование и доведение бота до рабочего состояния.

Код создавался с активным использованием AI-инструментов. При этом я проверял результат вручную: запускал сценарии, смотрел логи, исправлял проблемы, проверял миграции, тесты, CSV export и итоговое поведение бота.

Screenshots

Главное меню

Выбор типа заявки

Запрос контакта

Заявка отправлена

Админ-панель

Что умеет бот

Пользовательский сценарий:

• просмотр главного меню
• просмотр страниц и разделов demo-профиля
• чтение информации об услугах
• выбор типа обращения
• отправка заявки
• сбор контакта пользователя
• отправка уведомления администратору о новой заявке

Админский сценарий:

• получение уведомлений о новых заявках
• просмотр заявок
• просмотр контактов и текста обращения
• статусы заявки new → in_progress → done
• экспорт заявок в CSV
• Telegram CMS для контентных страниц и разделов

Demo profiles

В проекте есть несколько демо-профилей:

• lawyer
• psychologist
• realtor

Они показывают, как один lead engine можно адаптировать под разные ниши.

Demo profiles задают:

• тексты
• UI labels
• demo content
• lead form configuration
• названия кнопок и сценариев

Demo data note

Все имена, контакты, тексты, профили и бизнес-сценарии в этом репозитории являются демонстрационными.

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

Технологический стек

• Python 3.11
• aiogram 3
• SQLAlchemy async
• Alembic
• SQLite для локальной разработки
• pytest
• Ruff
• Telegram Bot API

Архитектура

Проект построен вокруг нескольких слоёв:

core + plugins + profiles

Core

Базовая инфраструктура:

• запуск приложения
• конфигурация
• база данных
• middleware
• logging
• startup smoke-check
• Telegram CMS

Leads plugin

Leads plugin отвечает за:

• пользовательскую форму заявки
• сбор контакта
• сохранение lead request в базу данных
• уведомления администратору
• админский просмотр заявок
• CSV export

Profiles

Profiles задают нишу и демо-контент.

Один и тот же lead engine может использоваться с разными профилями.

Быстрый старт

1. Создать виртуальное окружение

python -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. Создать .env

cp .env.example .env

Минимально нужно указать:

TOKEN=123456:ABCDEF...
ADMIN_IDS=123456789

Пример .env для lead demo:

TOKEN=123456:ABCDEF...
ENV=dev
DB_URL=sqlite+aiosqlite:///./db.sqlite3

ADMIN_IDS=123456789

DEMO_PROFILE=lawyer
SEED_DEMO=1

ENABLE_BOOKING=0
ENABLE_LEADS=1
ENABLE_SHOP=0
ENABLE_GROUPS=0

DEBUG=0
DEBUG_SQL=0
LOG_LEVEL=INFO

3. Применить миграции

python -m alembic upgrade head

Важно: Alembic читает DB_URL из переменных окружения. Файл .env при запуске Alembic не загружается автоматически; для нестандартной базы передавайте DB_URL=... прямо в команде.

4. Проверить smoke-сборку

TOKEN=123456:TEST_TOKEN_FOR_LOCAL_SMOKE_ONLY \
DEBUG=0 \
ADMIN_IDS=123456789 \
DEMO_PROFILE=lawyer \
SEED_DEMO=0 \
ENABLE_BOOKING=0 \
ENABLE_LEADS=1 \
ENABLE_SHOP=0 \
ENABLE_GROUPS=0 \
python app.py --smoke

Ожидаемый результат:

SMOKE OK

5. Запустить бота

python app.py

Demo profile запуск

Первый запуск с demo seed:

SEED_DEMO=1 DEMO_PROFILE=lawyer ENABLE_LEADS=1 ENABLE_BOOKING=0 python app.py

После первичного заполнения базы:

SEED_DEMO=0 DEMO_PROFILE=lawyer ENABLE_LEADS=1 ENABLE_BOOKING=0 python app.py

Для другого demo profile лучше использовать новую пустую базу или другой DB_URL.

Важно: Alembic читает DB_URL из переменных окружения. Сам файл .env при запуске Alembic не загружается автоматически, поэтому для нестандартной базы DB_URL лучше передавать прямо в команде.

Пример миграции для отдельной базы:

DB_URL=sqlite+aiosqlite:///./realtor.sqlite3 python -m alembic upgrade head

Переменные окружения

Переменная	Назначение	Пример
TOKEN	Telegram bot token	123456:ABCDEF...
ENV	Режим окружения	dev
DB_URL	URL базы данных	sqlite+aiosqlite:///./db.sqlite3
ADMIN_IDS	Telegram ID админов через запятую	123456789
DEMO_PROFILE	Активный demo profile	lawyer
SEED_DEMO	Заполнять БД demo data при старте	0 или 1
ENABLE_BOOKING	Отключить booking plugin для lead demo	0
ENABLE_LEADS	Включить leads plugin	1
ENABLE_SHOP	Отключить shop plugin для lead demo	0
ENABLE_GROUPS	Отключить group plugin для lead demo	0
DEBUG_SQL	SQL logging	0
LOG_LEVEL	Уровень логирования	INFO

Миграции

Применить миграции:

python -m alembic upgrade head

Создать новую миграцию после изменения моделей:

alembic revision --autogenerate -m "describe change"
python -m alembic upgrade head

Проверки

python -m compileall -q .
ruff check .
python -m pytest -q

TOKEN=123456:TEST_TOKEN_FOR_LOCAL_SMOKE_ONLY \
DEBUG=0 \
ADMIN_IDS=123456789 \
DEMO_PROFILE=lawyer \
SEED_DEMO=0 \
ENABLE_BOOKING=0 \
ENABLE_LEADS=1 \
ENABLE_SHOP=0 \
ENABLE_GROUPS=0 \
python app.py --smoke

Структура проекта

app.py
config.py
alembic/
common/
database/
filters/
handlers/
keyboards/
middlewares/
plugins/
profiles/
tests/
utils/

Ключевые директории:

• plugins/leads/ — lead product logic
• profiles/ — demo profiles
• database/ — SQLAlchemy models and ORM helpers
• handlers/ — base user/admin/CMS handlers
• alembic/ — database migrations
• tests/ — automated tests

Связь с base template

Telegram Bot Template показывает общую архитектуру.

Отдельная установка base template не требуется: этот репозиторий запускается самостоятельно.

В репозитории также присутствуют унаследованные от base template плагины booking, shop и groups: они сохранены для демонстрации модульности платформы и отключены в lead mode через ENABLE_BOOKING=0, ENABLE_SHOP=0, ENABLE_GROUPS=0.

Lead Bot показывает конкретный коммерческий сценарий: контентные страницы, форма заявки, сбор контакта, сохранение лида, уведомление администратора и экспорт заявок.

Ограничения

Этот репозиторий не является:

• SaaS-сервисом
• CRM-системой
• e-commerce bot
• универсальным framework
• готовым boxed-product для всех ниш без адаптации

Это portfolio-ready lead implementation, которую можно доработать под конкретного специалиста или бизнес-сценарий.