Andrew K. Choi
48f8c6f0eb
MAJOR FIXES: ✅ Fixed UserBot container startup by making TELEGRAM_BOT_TOKEN optional ✅ Broke circular import chain between app modules ✅ Made Config.validate() conditional for UserBot-only mode ✅ Removed unused celery import from userbot_service.py INTEGRATION: ✅ UserBot menu now accessible from main bot /start command ✅ Added 🤖 UserBot button to main keyboard ✅ Integrated userbot_manager.py handlers: - userbot_menu: Main UserBot interface - userbot_settings: Configuration - userbot_collect_groups: Gather all user groups - userbot_collect_members: Parse group members ✅ UserBot handlers properly registered in ConversationHandler CONTAINERS: ✅ tg_autoposter_bot: Running and handling /start commands ✅ tg_autoposter_userbot: Running as standalone microservice ✅ All dependent services (Redis, PostgreSQL, Celery workers) operational STATUS: Bot is fully operational and ready for testing
187 lines
5.3 KiB
Markdown
187 lines
5.3 KiB
Markdown
# 🤖 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
|