InstaLeadMagnitBot

Instagram Lead Magnet Bot - автоматическая система лидогенерации через Instagram. Мониторит комментарии под постами, отслеживает ключевые слова и отправляет персонализированные сообщения в Direct.

Возможности

• Мониторинг комментариев - автоматическое отслеживание комментариев под выбранными постами
• Ключевые слова - триггеры для отправки сообщений (exact/contains/regex)
• Шаблоны сообщений - персонализированные сообщения с переменными
• Правила - гибкая связка "ключевое слово → шаблон → пост"
• Welcome-сообщения - автоматические приветствия новым подписчикам
• Массовые рассылки - broadcast по сегментам пользователей
• Google Sheets логирование - запись всех событий в таблицу
• Telegram-бот - полное управление через Telegram

Архитектура

┌─────────────────────────────────────────────────────────────┐
│                       main.py                                │
│        (Инициализация, event loop, координация)             │
└─────────────────────────────────────────────────────────────┘
         │           │           │           │           │
         ▼           ▼           ▼           ▼           ▼
┌──────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Telegram Bot │ │ Comment  │ │ Direct   │ │ Follower │ │Broadcast │
│ (admin/bot)  │ │ Monitor  │ │ Messenger│ │ Monitor  │ │ Manager  │
└──────────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │   Google Sheets Logger        │
              └───────────────────────────────┘

Установка

1. Клонирование репозитория

git clone https://github.com/ircitdev/devtools.git
cd InstaLeadMagnitBot

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

python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

3. Установка зависимостей

pip install -r requirements.txt

4. Настройка конфигурации

Скопируйте .env.example в .env и заполните:

# Instagram
INSTAGRAM_USERNAME=your_username
INSTAGRAM_PASSWORD=your_password
INSTAGRAM_SESSION_FILE=session.json

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_bot_token
ADMIN_TELEGRAM_IDS=123456789

# Database
DATABASE_URL=sqlite+aiosqlite:///./data/bot.db

# Rate Limiting
CHECK_INTERVAL_SECONDS=60
MESSAGE_DELAY_MIN_SECONDS=30
MESSAGE_DELAY_MAX_SECONDS=60
MAX_MESSAGES_PER_HOUR=50

# Logging
LOG_LEVEL=INFO
LOG_FILE=logs/bot.log

# Google Sheets (опционально)
GOOGLE_SHEETS_ENABLED=true
GOOGLE_CREDENTIALS_FILE=credentials.json
GOOGLE_SPREADSHEET_ID=your_spreadsheet_id

5. Настройка Google Sheets (опционально)

1. Создайте проект в Google Cloud Console
2. Включите Google Sheets API
3. Создайте Service Account и скачайте JSON-ключ
4. Поместите файл как credentials.json в корень проекта
5. Откройте доступ к таблице для email сервисного аккаунта

6. Запуск

python run.py

Управление через Telegram

Интерфейс с кнопками

Бот использует упрощенный интерфейс с inline-кнопками. Введите /start и вы увидите главное меню:

┌─────────┬─────────┐
│ Статус  │ Посты   │
├─────────┼─────────┤
│ Слова   │ Шаблоны │
├─────────┼─────────┤
│ Правила │ Привет  │
├─────────┼─────────┤
│ Рассылки│ Справка │
└─────────┴─────────┘

Команды меню

Команда	Описание
/start	Главное меню с кнопками
/pause	Приостановить мониторинг
/resume	Возобновить мониторинг
/instahow	Проверка подключения к Instagram

Навигация

Все функции доступны через кнопки:

• Статус - статистика бота
• Посты - управление постами
• Слова - ключевые слова
• Шаблоны - шаблоны сообщений
• Правила - связка слов и шаблонов
• Приветствие - welcome-сообщения
• Рассылки - массовые broadcast
• Справка - открывает WebApp со справкой

Команды для добавления

Команда	Описание
/add_post <url>	Добавить пост
/add_keyword <word>	Добавить слово
/add_template <name> | <text>	Добавить шаблон
/add_rule <kw_id> <tpl_id> [post_id]	Создать правило
/set_welcome <text>	Установить приветствие
/broadcast <segment> | <name> | <message>	Создать рассылку

Переменные в шаблонах:

• {username} - имя пользователя
• {post_url} - URL поста
• {keyword} - сработавшее ключевое слово

Пример использования

Базовый сценарий

1. Добавить пост:

   /add_post https://instagram.com/p/ABC123
   

2. Добавить ключевое слово:

   /add_keyword ГАЙД
   

3. Создать шаблон:

   /add_template Приветствие | Привет, {username}! Держи гайд: https://example.com
   

4. Создать правило:

   /add_rule 1 1
   

Теперь когда кто-то напишет "ГАЙД" в комментарии, бот отправит ему DM.

Welcome-сообщения

/set_welcome Привет, {username}! Спасибо за подписку! Вот ссылка на бесплатные материалы: https://example.com
/toggle_welcome

Массовая рассылка

/segments
/broadcast followers 7 | Акция | Привет {username}! Только для подписчиков - скидка 50%!

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

InstaLeadMagnitBot/
├── src/
│   ├── __init__.py
│   ├── main.py                  # Главный модуль
│   ├── config.py                # Конфигурация
│   ├── instagram/
│   │   ├── client.py            # Instagram API клиент
│   │   ├── monitor.py           # Мониторинг комментариев
│   │   ├── messenger.py         # Отправка DM
│   │   ├── follower_monitor.py  # Мониторинг подписчиков
│   │   └── broadcast_manager.py # Массовые рассылки
│   ├── core/
│   │   ├── matcher.py           # Поиск ключевых слов
│   │   └── rules.py             # Движок правил
│   ├── database/
│   │   ├── models.py            # SQLAlchemy модели
│   │   └── repository.py        # CRUD операции
│   ├── admin/
│   │   ├── bot.py               # Telegram бот
│   │   └── handlers/            # Обработчики команд
│   │       ├── common.py
│   │       ├── menu.py          # Inline-меню с кнопками
│   │       ├── posts.py
│   │       ├── keywords.py
│   │       ├── templates.py
│   │       ├── rules.py
│   │       ├── control.py
│   │       ├── welcome.py
│   │       ├── broadcasts.py
│   │       ├── instagram.py     # Управление сессией Instagram
│   │       └── help.py          # WebApp справка
│   └── utils/
│       ├── helpers.py           # Утилиты
│       └── sheets_logger.py     # Google Sheets логгер
├── data/                        # База данных
├── logs/                        # Логи
├── .env                         # Конфигурация
├── .env.example                 # Пример конфигурации
├── credentials.json             # Google API ключ
├── requirements.txt
└── run.py                       # Точка входа

Google Sheets логирование

При включенном логировании автоматически создаются вкладки:

Вкладка	Содержимое
Events	Запуск, остановка, изменения конфигурации
SentMessages	Отправленные DM (username, status, preview)
NewFollowers	Новые подписчики (welcome sent: Yes/No)
Comments	Все комментарии (action: dm_queued/already_messaged/no_match)
Errors	Ошибки (component, type, message)
Broadcasts	Массовые рассылки (sent/failed/status)
Settings	Посты, ключевые слова, шаблоны, правила

Логируемые события

Comments - каждый обработанный комментарий:

• dm_queued - найдено совпадение, DM поставлен в очередь
• already_messaged - пользователь уже получал сообщение
• no_match - нет совпадения с ключевыми словами

NewFollowers - новые подписчики:

• Записывается username, user_id, отправлено ли welcome-сообщение
• Welcome отправляется только тем, кто подписался ПОСЛЕ запуска бота

SentMessages - все отправленные DM:

• Статус: sent/failed
• Preview первых 100 символов сообщения

Вкладка Settings автоматически обновляется при каждом запуске бота и содержит полный обзор текущей конфигурации.

Rate Limiting

Для защиты от блокировки Instagram:

Параметр	Значение
Проверка комментариев	каждые 60 сек
Задержка между DM	30-60 сек
Лимит DM	50/час
Задержка broadcast	45-90 сек
Лимит broadcast	30/час

Модели данных

Модель	Описание
Post	Отслеживаемый пост
Keyword	Ключевое слово (exact/contains/regex)
MessageTemplate	Шаблон сообщения
Rule	Связка keyword → template → post
SentMessage	Лог отправленных сообщений
ProcessedComment	Обработанные комментарии
WelcomeSettings	Настройки приветствий
ProcessedFollower	Приветствованные подписчики
Broadcast	Кампания рассылки
BroadcastRecipient	Получатели рассылки

Технологии

• Python 3.11+
• instagrapi - Instagram Private API
• python-telegram-bot 20.x - Async Telegram Bot
• SQLAlchemy 2.0 + aiosqlite - Async ORM
• gspread - Google Sheets API
• pydantic-settings - Конфигурация
• loguru - Логирование

Безопасность

• Храните .env и credentials.json в секрете
• Не коммитьте файлы с паролями
• Используйте отдельный Instagram аккаунт
• Соблюдайте rate limits
• Добавьте файлы в .gitignore

Лицензия

MIT License