Telegram Group Exporter

A Python CLI tool for exporting Telegram group member lists to JSON files using your personal account. Uses Telethon (Telegram user API, not Bot API) with built-in safety features: sequential processing, rate-limit handling, session persistence, and automatic deduplication.

Quick Start

Use the Claude Code Skill (Easiest)

/telegram-exporter --list                    # List all groups
/telegram-exporter --id 2805943040           # Export one group
/telegram-exporter --ids 123,456,789         # Export multiple groups
/telegram-exporter --names "GroupName"       # Export by name

Type /telegram-exporter --help for full documentation.

Run from Source Code

# 1. Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate     # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Set up .env (see below)
cp .env.example .env
# Edit .env with your credentials

# 4. Run
python run.py --list-groups          # List all groups
python run.py --group-id 2805943040  # Export group by ID
python run.py --names "GroupName"    # Export by name

Authentication

First Login

On first run, you'll be prompted to:

1. Enter a verification code sent to your Telegram account
2. Enter your 2FA password (if enabled)

The session is saved locally in telegram_session.session and reused on subsequent runs.

Security Risks & Safety Measures

⚠️ Risks:

• Your personal Telegram account is used (not a bot)
• You need valid API credentials from my.telegram.org
• Member data is exported to local JSON files

✅ Safety features built-in:

• Sequential processing (no parallel requests)
• 2-second delays between requests + random jitter
• Automatic rate-limit detection and graceful stop
• Session file stays local (not transmitted)
• Conservative by default (safe settings for main accounts)
• Transparent logging of all actions

Best practices:

• Keep your .env file private (in .gitignore)
• Use strong 2FA on your Telegram account
• Review exported JSON before sharing
• Don't commit .env or session files to version control

Required Environment Variables

Create .env with these required variables:

# REQUIRED - Get from https://my.telegram.org/apps
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE=+1234567890          # Your phone number with country code

# OPTIONAL - Defaults shown
OUTPUT_DIR=./exports                 # Where to save JSON files
DELAY_BETWEEN_REQUESTS_MS=2000      # Wait between requests (ms)
DELAY_JITTER_MS=1000                # Random jitter to avoid patterns
DRY_RUN=false                        # Test without saving files
MAX_GROUPS=0                         # Limit groups (0 = no limit)
MAX_MEMBERS_PER_GROUP=0              # Limit members per group (0 = no limit)

Output Format

One JSON file per group in exports/:

{
  "group_name": "GroupName",
  "members": [
    {
      "telegram_username": "user123",
      "telegram_userhandle": "@user123"
    }
  ],
  "exported_at": "2026-03-18T12:00:00Z",
  "total_members": 1
}

Features:

• Only members with public usernames are exported
• Automatically deduplicated
• Empty/invalid entries filtered out
• Users in exclude_list.json are skipped

Optional: Exclude List

Create exclude_list.json to filter out specific users:

["@spam_bot", "@fake_user", "another_handle"]

Project Structure

telegram-exporter/
├── .claude/skills/telegram-exporter/  # Claude Code skill
├── src/                               # Source code
├── run.py                             # Main entry point
├── requirements.txt                   # Dependencies
├── .env.example                       # Config template
├── .env                               # Your actual config (gitignored)
├── exclude_list.json.example          # Exclude list template
├── exports/                           # Output folder (auto-created)
└── README.md                          # This file

Technology

• Telethon - Telegram user API client
• Python 3.8+ - Runtime
• asyncio - Async/await for efficient I/O
• python-dotenv - Environment variable management

License

MIT