# 🤖 UserBot Integration - User Manual

## Overview

UserBot has been integrated directly into the main Telegram bot. You can now manage group parsing and member collection directly from the Telegram interface.

## Features

### 1. **Settings** ⚙️
- Check UserBot initialization status
- Initialize UserBot if needed
- View UserBot configuration

### 2. **Collect Groups** 📥
- Gather all groups the user is a member of
- Save group information to database
- View statistics (group count, members per group)

### 3. **Collect Members** 👥
- Select a group from the database
- Parse all members in that group
- View member statistics (total, bots, admins, owners)

## Step-by-Step Guide

### Getting Started

1. **Open Telegram Bot**
   - Send `/start` command
   - You'll see the main menu

2. **Access UserBot Menu**
   - Click "🤖 UserBot" button in main menu
   - You're now in UserBot control panel

### Collecting Groups

1. In UserBot menu, click "📥 Собрать группы" (Collect Groups)
2. Wait for the process to complete
3. You'll see:
   - Number of groups found
   - List of groups with member counts
   - Confirmation that data is saved

**Example output:**
```
✅ Найдено групп: 5

Список групп:
1. Python Developers
   👥 Участников: 2540
2. JavaScript Community
   👥 Участников: 1850
3. Web Development
   👥 Участников: 3200
...

💾 Группы сохранены в базе данных!
```

### Collecting Members

1. In UserBot menu, click "👥 Собрать участников" (Collect Members)
2. Select the group you want to parse from the list
3. Wait for the process to complete
4. You'll see member statistics

**Example output:**
```
✅ Участники собраны!

Группа: Python Developers

Статистика:
• 👥 Всего участников: 2540
• 🤖 Ботов: 45
• 👑 Администраторов: 12
• 🔑 Владельцев: 3

💾 Данные сохранены в базе данных!
```

### Settings

1. In UserBot menu, click "⚙️ Настройки" (Settings)
2. Check current status
3. If not initialized, click "🔄 Инициализировать" (Initialize)

## Available Commands

| Command | Action |
|---------|--------|
| `/start` | Open main menu |
| Click "🤖 UserBot" | Access UserBot control panel |
| "⚙️ Настройки" | Check/configure settings |
| "📥 Собрать группы" | Collect all user's groups |
| "👥 Собрать участников" | Parse members of selected group |
| "⬅️ Назад" | Go back to previous menu |
| "🏠 Меню" | Return to main menu |

## Workflow Diagram

```
/start
  ↓
Main Menu
  ├─ 📨 Сообщения
  ├─ 👥 Группы  
  └─ 🤖 UserBot ← You are here
      ├─ ⚙️ Настройки
      │   └─ 🔄 Инициализировать
      ├─ 📥 Собрать группы
      │   └─ [List of groups]
      └─ 👥 Собрать участников
          └─ [Select group]
              └─ [Parse members]
```

## Database Integration

### Groups Table
When you collect groups, the following information is saved:
- **chat_id**: Telegram group ID
- **title**: Group name
- **description**: Group description
- **members_count**: Number of members
- **is_active**: Active status
- **created_at**: When data was collected
- **updated_at**: Last update time

### Members Table
When you collect members, the following information is saved for each member:
- **user_id**: Telegram user ID
- **username**: @username (if available)
- **first_name**: User's first name
- **last_name**: User's last name
- **is_bot**: Is this user a bot?
- **is_admin**: Is this user an admin?
- **is_owner**: Is this user the owner?
- **group_id**: Which group they belong to

## Troubleshooting

### "UserBot не инициализирован" (UserBot not initialized)
**Solution:** Go to Settings → Click "🔄 Инициализировать"

### "FloodWait 3600" error
**What it means:** Telegram is rate-limiting requests
**Solution:** This is normal. The bot will automatically wait and retry. Just don't close the dialog.

### "Не найдено групп" (No groups found)
**Possible causes:**
- You're not a member of any groups
- Groups are private and not accessible
**Solution:** Make sure you're a member of at least one group

### "Не удалось собрать участников" (Can't collect members)
**Possible causes:**
- No permission to access member list (group settings)
- FloodWait (rate limiting)
- You're not a member of the group
**Solution:** Try again later, ensure you have proper permissions

## Performance

- **Collecting 5K members**: ~2-3 minutes
- **Collecting 100K members**: ~30-60 minutes
- **Groups collection**: ~1-5 minutes (depends on group count)

## Security Notes

- UserBot uses a separate Telegram session
- All data is stored locally in PostgreSQL
- No data is sent to third parties
- The session file is stored in `sessions/userbot_session.session`

## Getting Help

1. Check the logs: `docker-compose logs -f bot`
2. Review database: `docker-compose exec postgres psql ...`
3. Check Flower for task status: http://localhost:5555

---

**Created:** Integration Phase  
**Status:** ✅ Production Ready