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`:
```python
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`:
```python
async def parse_groups_user_in()      # Get all user's groups
```

### In `app/database/repository.py`:
```python
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:**
   ```bash
   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`):
```python
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