TG_autoposter/USERBOT_INTEGRATION_QUICK_START.md

🎯 UserBot Integration - Quick Start

What's New?

UserBot management is now integrated into the main Telegram bot. You can:

• ✅ Manage UserBot settings
• ✅ Collect all groups you're a member of
• ✅ Parse members from selected groups
• ✅ Save everything to PostgreSQL

Menu Structure

/start
│
└─ Main Menu 🤖
   ├─ 📨 Messages (existing)
   ├─ 👥 Groups (existing)
   └─ 🤖 UserBot ← NEW!
       ├─ ⚙️ Settings
       │   └─ Check status / Initialize
       ├─ 📥 Collect Groups
       │   └─ Get all groups you're in
       └─ 👥 Collect Members
           └─ Select group → Parse members

Three Simple Steps

Step 1: Initialize UserBot

1. Send /start
2. Click "🤖 UserBot"
3. Click "⚙️ Настройки" (Settings)
4. Click "🔄 Инициализировать" (Initialize)

Step 2: Collect Groups

1. In UserBot menu, click "📥 Собрать группы" (Collect Groups)
2. Wait for completion
3. See list of your groups and member counts
4. Data saved to DB automatically

Step 3: Collect Members

1. In UserBot menu, click "👥 Собрать участников" (Collect Members)
2. Select a group from the list
3. Wait for member parsing
4. See statistics (total, bots, admins, owners)
5. Data saved to DB automatically

File Changes

New Files Created

• app/handlers/userbot_manager.py - UserBot control handlers
• USERBOT_INTEGRATION_GUIDE.md - Full documentation

Files Modified

• app/__init__.py - Added UserBot handlers and ConversationHandler import
• app/handlers/__init__.py - Added userbot handler exports
• app/utils/keyboards.py - Added MANAGE_USERBOT callback type, updated main keyboard
• app/database/repository.py - Added get_active_groups() and get_group_by_id() methods
• app/userbot/parser.py - Added parse_groups_user_in() method

Key Functions

In app/handlers/userbot_manager.py:

async def userbot_menu()              # Main UserBot menu
async def userbot_settings()          # Settings dialog
async def userbot_init()              # Initialize UserBot
async def userbot_collect_groups()    # Collect groups
async def userbot_collect_members()   # Select group for parsing
async def userbot_parse_members()     # Parse members of group
async def cancel_userbot()            # Cancel operation

In app/userbot/parser.py:

async def parse_groups_user_in()      # Get all user's groups

In app/database/repository.py:

async def get_active_groups()         # Get active groups
async def get_group_by_id()           # Get group by ID

Database

New/Modified Tables

• groups - Stores group information
• group_members - Stores member information

Data Saved

Groups:

• chat_id, title, description
• members_count, is_active
• created_at, updated_at

Members:

• user_id, username, first_name, last_name
• is_bot, is_admin, is_owner
• group_id (reference to group)

Testing

Before deploying, test:

1. Initialize:

   /start → 🤖 UserBot → ⚙️ Settings → 🔄 Initialize
   

2. Collect Groups:

   🤖 UserBot → 📥 Collect Groups → ✅ See list
   

3. Collect Members:

   🤖 UserBot → 👥 Collect Members → Select group → ✅ See stats
   

4. Verify Data:

   docker-compose exec postgres psql -U admin -d tg_autoposter
   SELECT COUNT(*) FROM groups;
   SELECT COUNT(*) FROM group_members;
   \q
   

Workflow States

The UserBot manager uses these states (in userbot_manager.py):

USERBOT_MENU = 1
USERBOT_SETTINGS = 2
USERBOT_COLLECTING_GROUPS = 3
USERBOT_SELECT_GROUP = 4
USERBOT_COLLECTING_MEMBERS = 5

Error Handling

The integration includes error handling for:

• ❌ UserBot not initialized → Prompt to initialize
• ❌ FloodWait errors → Graceful retry
• ❌ Permission errors → Inform user
• ❌ No groups found → Clear message
• ❌ Database errors → Error reporting

Callbacks

New callbacks added:

userbot_menu              - Main menu
userbot_settings          - Settings dialog
userbot_init              - Initialize UserBot
userbot_collect_groups    - Collect groups
userbot_collect_members   - Select group
userbot_members_\d+       - Parse specific group

Next Steps

1. ✅ Test the new UserBot menu
2. ✅ Verify group collection works
3. ✅ Verify member collection works
4. ✅ Check database for saved data
5. ✅ Deploy to production

Full Documentation

For detailed information, see:

• USERBOT_INTEGRATION_GUIDE.md - Complete user manual
• docs/USERBOT_MICROSERVICE.md - Technical details
• USERBOT_README.md - Overview in Russian

---

Status: ✅ Ready for Testing
Date: 2024
Components: 1 new file + 5 files modified