telegram-groupfactory/CONFIGURATION_GUIDE.md

# Telegram Group Factory - Configuration Guide

## Overview

This guide explains how to configure users to be added to newly created groups and manage GroupHelp backup QR data via the bot.

## Setting Up Default Users for New Groups

### What are Default Users?

Default users are a list of user IDs that will be **automatically added to every new group** created without explicitly specifying users.

### Step 1: Add Users to the Database

First, add the users you want to manage using the bot commands:

```
/add_user <username>
```

Example:
```
/add_user alice
/add_user bob
/add_user charlie
```

The bot will respond with:
```
✅ User alice added successfully (ID: 1234567890)
```

**Note:** Keep track of the user IDs returned by the bot - you'll need these for configuration.

### Step 2: View All Users

Check all available users in the database:

```
/users
```

This will show:
```
👥 All Users (3):
• alice (alice) - ID: 1234567890
• bob (bob) - ID: 0987654321
• charlie (charlie) - ID: 5555555555
```

### Step 3: Configure Default Users

#### Option A: Set Default Users (Replace Existing)
Replace the entire default users list:

```
/set_default_users 1234567890 0987654321 5555555555
```

Response:
```
✅ Default users updated successfully:
  • alice (ID: 1234567890)
  • bob (ID: 0987654321)
  • charlie (ID: 5555555555)
```

#### Option B: Add Users to Default List (Append)
Add new users to the existing default list:

```
/add_default_users 1111111111
```

Response:
```
✅ Users added to default list:
  • diana (ID: 1111111111)
```

#### Option C: Remove Users from Default List
Remove specific users from the default list:

```
/remove_default_users 5555555555
```

Response:
```
✅ Users removed from default list:
  • charlie (ID: 5555555555)
```

### Step 4: Verify Default Users

Check what users are currently configured as defaults:

```
/get_default_users
```

Response:
```
📋 Current default users for new groups:
  • alice (ID: 1234567890)
  • bob (ID: 0987654321)
  • diana (ID: 1111111111)
```

### Step 5: Create Groups with Default Users

Now whenever you create a new group **without specifying users**, all default users will be automatically added:

```
/create_group ProjectAlpha
```

This will automatically add alice, bob, and diana to the ProjectAlpha group.

You can also create a group with **specific users** (overriding defaults):

```
/create_group ProjectBeta 1234567890,0987654321
```

This will create ProjectBeta with only alice and bob, regardless of the default list.

---

## GroupHelp QR Backup Configuration

### What is QR Backup Data?

QR backup data is the GroupHelp settings backup payload generated by GroupHelp itself. It is used to copy GroupHelp settings, such as welcome-message configuration, from one group to another by rendering the payload as a QR image and sending it with a `.importbackup` caption.

### Step 1: Generate or Obtain QR Code

Generate the QR backup from GroupHelp in the source group. You can either store the decoded payload directly, or start the interactive importer and forward the original GroupHelp QR image message.

### Step 2: Set GroupHelp QR Backup Data

Store the GroupHelp QR backup payload directly:

```
/admin_set_qr YOUR_QR_PAYLOAD_HERE
```

Example:
```
/admin_set_qr new_390530c569ec8902a6cbd8482d51d70d2857d4a0
```

Or start the interactive QR importer:

```
/admin_set_qr
```

Then forward the original GroupHelp QR image message into the staff chat. The forwarded image message must have `.importbackup` as its caption/body. GroupFactory decodes the QR image and stores the decoded payload.

Response:
```
✅ QR backup data updated successfully!

Data: `new_390530c569ec8902a6cbd8482d51d70d2857d4a0`
```

### Step 3: Retrieve GroupHelp QR Backup Data

Retrieve the stored GroupHelp QR backup data anytime:

```
/admin_get_qr
```

Response:
```
📊 Current QR Backup Data:
`new_390530c569ec8902a6cbd8482d51d70d2857d4a0`
```

### Step 4: Use QR Backup with GroupHelp

Once you have the QR backup data stored, you can:
1. Retrieve it with `/admin_get_qr`
2. Let GroupFactory render it as a QR image during `!newgrp`
3. Let GroupHelp import the backed-up settings from the `.importbackup` image message

---

## Database Structure

The configuration data is stored in MongoDB with the following structure:

### Default Users Collection (`group_config`)
```json
{
  "_id": ObjectId(...),
  "key": "default_users",
  "value": [1234567890, 0987654321, 1111111111]
}
```

### GroupHelp QR Backup Collection (`COLLECTION_NAME`)
```json
{
  "_id": ObjectId(...),
  "key": "qr_backup_data",
  "value": "0001a8ac0123456789abcdef0123456789abcdef01234567"
}
```

---

## Common Workflows

### Workflow 1: Initial Setup

```bash
# 1. Add users
/add_user alice
/add_user bob
/add_user charlie

# 2. Configure default users (save the IDs from step 1)
/set_default_users 1234567890 0987654321 5555555555

# 3. Verify configuration
/get_default_users

# 4. Create a test group
/create_group TestGroup
```

### Workflow 2: Adding New Users to Existing Groups

```bash
# 1. Add new user
/add_user diana

# 2. Add diana to default users
/add_default_users 1111111111

# 3. Future groups will include diana automatically
/create_group NewProject
```

### Workflow 3: GroupHelp QR Backup Import

```bash
# Retrieve the stored GroupHelp QR payload:
/admin_get_qr

# During !newgrp, GroupFactory sends the payload as a QR image with:
.importbackup
```

---

## Troubleshooting

### Issue: "No default users configured yet"
**Solution:** Run `/set_default_users` with at least one user ID.

### Issue: "User IDs {[123, 456]} do not exist in database"
**Solution:** First add these users with `/add_user <username>` and get their IDs.

### Issue: Group created but users not added
**Solution:** 
1. Check if default users are configured: `/get_default_users`
2. Verify users exist: `/users`
3. Manually add users to group: `/add_users <group_id> <user_id1>,<user_id2>`

### Issue: GroupHelp QR backup data appears empty
**Solution:** 
1. Check if data was stored: `/admin_get_qr`
2. Re-set the data: `/admin_set_qr <your_qr_payload>` or use `/admin_set_qr` and forward the `.importbackup` QR image

---

## Environment Variables

Make sure these are set in your `.env` file:

```bash
TELETHON_API_ID=your_api_id
TELETHON_API_HASH=your_api_hash
TELETHON_TOKEN=your_session_token

MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=groupfactory
MONGODB_COLLECTION=ghconfig

STAFF_CHAT_ID=your_staff_chat_id
FACTORY_BOT_ID=your_bot_id
FACTORY_BOT_USERNAME=your_bot_username
```

---

## API Reference

### User Management Commands
- `/users` - List all users
- `/user <user_id>` - Get specific user info
- `/add_user <username>` - Add new user
- `/delete_user <user_id>` - Delete user

### Group Management Commands
- `/create_group <name>` - Create group with default users
- `/create_group <name> <id1>,<id2>` - Create group with specific users
- `/add_users <group_id> <id1>,<id2>` - Add users to existing group
- `/get_group <group_id>` - Get group information

### Configuration Commands
- `/get_default_users` - View current default users
- `/set_default_users <id1> <id2> ...` - Set default users (replace)
- `/add_default_users <id1> <id2> ...` - Add users to default list
- `/remove_default_users <id1> <id2> ...` - Remove users from default list
- `/admin_get_qr` - View GroupHelp QR backup data
- `/admin_set_qr <qr_payload>` - Set GroupHelp QR backup data directly
- `/admin_set_qr` - Decode a forwarded `.importbackup` QR image
- `/config_help` - Show configuration command help
- `/help` - Show all available commands

---

## Advanced Usage

### Using in Docker Compose

```yaml
version: '3.8'
services:
  groupfactory:
    build: .
    environment:
      TELETHON_API_ID: ${TELETHON_API_ID}
      TELETHON_API_HASH: ${TELETHON_API_HASH}
      TELETHON_TOKEN: ${TELETHON_TOKEN}
      MONGODB_URI: mongodb://mongo:27017
      MONGODB_DATABASE: groupfactory
      MONGODB_COLLECTION: ghconfig
    depends_on:
      - mongo

  mongo:
    image: mongo:latest
    volumes:
      - mongo_data:/data/db

volumes:
  mongo_data:
```

### Accessing Configuration via MongoDB Client

```bash
# Connect to MongoDB
mongo mongodb://localhost:27017/groupfactory

# View default users
db.group_config.find()

# View GroupHelp QR backup
db.ghconfig.find({key: 'qr_backup_data'})
```

---

## Operational Notes

1. QR backup data is a GroupHelp configuration payload, not a Telegram or Telethon session.
2. During `!newgrp`, GroupFactory sends `.importbackup` with the stored GroupHelp settings as a QR image.
3. Limit configuration commands to trusted chats so group settings are changed intentionally.
4. Monitor command usage if multiple operators manage the same groups.

---

For more information or issues, check the project README.md or GitHub issues.