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)

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

GroupHelp 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: GroupHelp QR Backup Import

# 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:

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

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

# 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.