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.

GroupFactory supports multiple logical QR config groups. The built-in group is default; additional names such as sales, support, or alerts can each have their own stored QR payload and assigned Telegram groups.

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

Store a payload for a named logical QR group:

/admin_set_qr sales YOUR_SALES_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 for default.

For a named QR group, start the importer with:

/admin_set_qr_group sales

Response:

✅ QR backup image for `sales` decoded and stored successfully!

Data: `new_390530c569ec8902a6cbd8482d51d70d2857d4a0`

Step 3: Retrieve GroupHelp QR Backup Data

Retrieve the stored GroupHelp QR backup data anytime:

/admin_get_qr

Retrieve a named QR group:

/admin_get_qr sales

Response:

📊 Current QR Backup Data for `sales`:
`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

To resync the stored GroupHelp configuration across existing managed groups, run:

/admin_sync_qr

This sends the default stored .importbackup QR image only to unassigned owned group dialogs. It skips private chats and channels, and waits 30 seconds between each group.

Assign Telegram groups to named QR configs:

/admin_qr_group_add sales -1001234567890 -1009876543210
/admin_qr_groups

Sync one named QR group, or all logical groups sequentially:

/admin_sync_qr sales
/admin_sync_qr all

---

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_get_qr <qr_group> - View GroupHelp QR backup data for a named QR group
• /admin_set_qr <qr_payload> - Set default GroupHelp QR backup data directly
• /admin_set_qr <qr_group> <qr_payload> - Set named GroupHelp QR backup data directly
• /admin_set_qr - Decode a forwarded .importbackup QR image for default
• /admin_set_qr_group <qr_group> - Decode a forwarded .importbackup QR image for a named QR group
• /admin_qr_groups [qr_group] - List QR configs and assigned Telegram groups
• /admin_qr_group_add <qr_group> <telegram_group_id> ... - Assign Telegram groups to a QR config
• /admin_qr_group_remove <telegram_group_id> ... - Remove Telegram group QR config assignment
• /admin_sync_qr [qr_group|all] - Send stored .importbackup QR to owned assigned groups
• /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'})

# View all named GroupHelp QR backups
db.ghconfig.find({key: /^qr_backup_data/})

# View QR group assignments
db.ghconfig.find({key: 'qr_group_assignments'})

---

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