codex-tgmember 🔭

⚠️ For educational purposes only. Use responsibly and in compliance with Telegram's Terms of Service.

A Python package to scrape members from Telegram groups and add them to your own group — powered by Telethon.

---

✨ Features

Feature	Description
📋 Scrape Members	Export all visible group members to a CSV file
➕ Add Members	Bulk-add users from CSV by username or Telegram ID
📂 CSV Viewer	Display any member CSV file in the terminal
🔐 2FA Support	Handles two-step verification automatically
🛡️ Safe Fallback	Falls back gracefully when admin rights are missing

---

📦 Installation

From PyPI (after publishing)

pip install codex-tgmember

From source (local)

cd pack/
pip install .

---

🔑 Prerequisites

1. Python 3.7+
2. A Telegram account with a phone number
3. API credentials from my.telegram.org:
   • Go to API development tools
   • Create an app → copy api_id and api_hash

---

⚙️ Configuration

Option A — Use as a Python library

from tg_member_tool import TelegramMemberTool

tool = TelegramMemberTool(
    api_id=12345678,           # your API ID
    api_hash='your_api_hash',  # your API Hash
    phone='+94707728716'       # your phone with country code
)

# Start interactive menu
tool.run()

Option B — Edit cli.py and use the command line

Open pack/tg_member_tool/cli.py and fill in your credentials:

API_ID   = 12345678
API_HASH = 'your_api_hash_here'
PHONE    = '+94707728716'

Then run:

tg-member-tool

---

🚀 Usage

Interactive Menu

╔══════════════════════════════╗
║     Telegram Member Tool     ║
╚══════════════════════════════╝

  1. Scrape group members → CSV
  2. Add members from CSV
  3. Display CSV file

  Select option:

---

1️⃣ Scrape Members → CSV

tool.scrape_members()
# or pass index directly (no prompt):
tool.scrape_members(group_index=5)

Output file: members-groupname.csv

username,user_id,access_hash,name,group,group_id
john_doe,123456789,9876543210987654321,John Doe,My Group,1001234567

---

2️⃣ Add Members from CSV

tool.add_members('members-my-group.csv')
# or specify group and method directly:
tool.add_members('members.csv', group_index=2, method=1)

CSV format required:

username,user_id,access_hash
john_doe,123456789,9876543210987654321
jane_doe,987654321,1234567890123456789

Add methods:

• 1 — by username (more reliable, requires user to have a username)
• 2 — by Telegram ID (works even without a username)

---

3️⃣ Display CSV File

tool.display_csv('members-my-group.csv')

---

📁 Package Structure

pack/
├── pyproject.toml              ← Package config & metadata
├── LICENSE
├── README.md
└── tg_member_tool/
    ├── __init__.py             ← Package entry, exports TelegramMemberTool
    ├── core.py                 ← Main TelegramMemberTool class
    └── cli.py                  ← `tg-member-tool` command entry point

---

⚠️ Common Errors & Fixes

Error	Cause	Fix
SessionPasswordNeededError	2FA is enabled	Enter your 2FA password when prompted
ChatAdminRequiredError	Not admin of the group	Choose a group where you are admin
PeerFloodError	Too many requests	Wait several hours before trying again
UserPrivacyRestrictedError	User has privacy on	User is skipped automatically
AuthRestartError	Telegram internal issue	Re-run the script

---

🔐 Security Notes

• 🔑 Never share your api_id, api_hash, or .session file
• ❌ Never commit credentials to GitHub — add them to .gitignore
• ⏳ Respect Telegram's rate limits: limits.tginfo.me
• 👥 Only add users who have consented to join groups

---

📜 Disclaimer

This tool is provided for educational purposes only. The author is not responsible for:

• Account bans due to aggressive API use
• Privacy violations or spam complaints
• Any misuse of this software

Always comply with Telegram's Terms of Service.

---

📄 License

MIT © K.NIRMAL