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 backup QR code replication 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.

---

QR Code Backup Configuration

What is QR Backup Data?

QR backup data is a code that can be used to replicate or restore your bot's session across multiple instances. This is useful for:

• Disaster recovery
• Multi-instance deployment
• Session migration
• Backup and restore scenarios

Step 1: Generate or Obtain QR Code

Depending on your setup, you might have a QR code from:

• Bot session export
• Backup file
• Another instance

Step 2: Set QR Backup Data

Store the QR backup data in the database:

/set_qr_backup YOUR_QR_CODE_HERE

Example:

/set_qr_backup 0001a8ac0123456789abcdef0123456789abcdef01234567

Response:

✅ QR backup data updated successfully!

Data: `0001a8ac0123456789abcdef0123456789abcdef01234567`

Step 3: Retrieve QR Backup Data

Retrieve the stored QR backup data anytime:

/get_qr_backup

Response:

📊 Current QR Backup Data:
`0001a8ac0123456789abcdef0123456789abcdef01234567`

Step 4: Use QR Backup for Replication

Once you have the QR backup data stored, you can:

1. Export it from the database
2. Use it in deployment scripts
3. Pass it to other bot instances
4. Store it in version control (encrypted) for DR purposes

---

Database Structure

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

Default Users Collection (group_config)

{
  "_id": ObjectId(...),
  "key": "default_users",
  "value": [1234567890, 0987654321, 1111111111]
}

QR Backup Collection (COLLECTION_NAME)

{
  "_id": ObjectId(...),
  "key": "qr_backup_data",
  "value": "0001a8ac0123456789abcdef0123456789abcdef01234567"
}

---

Common Workflows

Workflow 1: Initial Setup

# 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

# 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: QR Code Backup & Restore

# On source instance:
/get_qr_backup
# Copy the QR code output

# On target instance:
/set_qr_backup <paste_qr_code_here>

# Verify it was stored
/get_qr_backup

---

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: QR backup data appears empty

Solution:

1. Check if data was stored: /get_qr_backup
2. Re-set the data: /set_qr_backup <your_qr_code>

---

Environment Variables

Make sure these are set in your .env file:

TELETHON_API_ID=your_api_id
TELETHON_API_HASH=your_api_hash
TELEGRAM_BOT_TOKEN=your_bot_token
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

---

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
• /get_qr_backup - View QR backup data
• /set_qr_backup <data> - Set QR backup data
• /config_help - Show configuration command help
• /help - Show all available commands

---

Advanced Usage

Using in Docker Compose

version: '3.8'
services:
  groupfactory:
    build: .
    environment:
      TELETHON_API_ID: ${TELETHON_API_ID}
      TELETHON_API_HASH: ${TELETHON_API_HASH}
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      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

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

# View default users
db.group_config.find()

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

---

Security Considerations

1. Never share QR backup data in public channels or version control
2. Encrypt sensitive data before storing in version control
3. Rotate credentials regularly especially after backups
4. Limit bot access to trusted chats only
5. Monitor command usage for suspicious activity

---

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