Telegram exporter

telegram-exporter

Export members from Telegram groups into JSON files using your personal account.

Overview

This skill allows you to export member lists from Telegram groups without leaving Claude Code. It uses the Telegram user API (not Bot API) with built-in safety features:

• Sequential processing (no parallel requests)
• Rate-limit detection and graceful handling
• 2-second delays between requests
• Session persistence
• Deduplication and filtering

Usage

Export members from one or multiple Telegram groups by providing:

1. Group ID(s) - Single ID or comma-separated list (fastest, no full scan)
2. Group name(s) - By name or partial match

Examples

Export one group by ID:

/telegram-exporter --id 2805943040

Export multiple groups by IDs (comma-separated):

/telegram-exporter --ids 2805943040,1234567890,9876543210

Export groups by name (partial match):

/telegram-exporter --names MyGroup "Work Team"

List all groups with their IDs:

/telegram-exporter --list

Getting Group IDs

Method 1: List All Groups

/telegram-exporter --list

Method 2: From web.telegram.org

1. Open https://web.telegram.org
2. Click the group
3. Extract ID from URL:

   https://web.telegram.org/a/#-1002805943040
                                 ^^^^^^^^^^^^^^
   

   Use: 2805943040 (without the -100 prefix)

Configuration

All settings are in the project's .env file. Key options:

Option	Default	Purpose
TELEGRAM_API_ID	Required	API credential from my.telegram.org
TELEGRAM_API_HASH	Required	API credential from my.telegram.org
TELEGRAM_PHONE	Required	Your phone number with country code
DRY_RUN	false	Test without saving files
MAX_GROUPS	0	Limit number of groups (0 = unlimited)
MAX_MEMBERS_PER_GROUP	0	Limit members per group (0 = unlimited)
DELAY_BETWEEN_REQUESTS_MS	2000	Delay between requests (ms)

Output

Creates JSON files in exports/ folder, one per group:

File: GroupName.json

{
  "group_name": "Coinly",
  "members": [
    {
      "telegram_username": "alice_smith",
      "telegram_userhandle": "@alice_smith"
    },
    {
      "telegram_username": "bob_jones",
      "telegram_userhandle": "@bob_jones"
    }
  ],
  "exported_at": "2026-03-17T14:23:45.123Z",
  "total_members": 2
}

Features

• ✅ One file per group
• ✅ Members with public usernames only
• ✅ Automatic deduplication
• ✅ Excludes users in exclude_list.json (if exists)
• ✅ ISO 8601 timestamps

Exclude List

Create exclude_list.json in project root to filter users:

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

Users in this list won't appear in exports. Handles work with or without @ prefix.

Testing

Use dry-run mode to test without saving files:

1. Edit .env:

   DRY_RUN=true
   MAX_GROUPS=1
   

2. Run:

   /telegram-exporter --id 2805943040
   

3. Check console output for what would be saved

4. When ready, change DRY_RUN=false and run again

First Setup

1. Get API credentials:

   • Visit https://my.telegram.org/apps
   • Log in with your Telegram account
   • Create app and copy API_ID and API_HASH

2. Configure:

   • Edit .env with your credentials:

     TELEGRAM_API_ID=your_id
     TELEGRAM_API_HASH=your_hash
     TELEGRAM_PHONE=+1234567890
     

3. List groups:

   /telegram-exporter --list
   

   First run will prompt for verification code via Telegram

4. Export:

   /telegram-exporter --id 2805943040
   

Safety Features

• Rate limit protection - Detects and stops gracefully on rate limits
• Sequential processing - One group at a time, never parallel
• Configurable delays - 2000ms default + random jitter
• Session persistence - Logs in once, reuses session
• Graceful errors - Skips inaccessible groups, logs warnings
• Data filtering - Deduplicates, excludes empty entries, filters excluded users

Troubleshooting

"Invalid group ID"

• Ensure ID is a number
• Remove any minus sign: use 2805943040 not -1002805943040

"Group not found"

• Check spelling with /telegram-exporter --list
• Use exact group name

Rate Limited

• Increase delays in .env:

  DELAY_BETWEEN_REQUESTS_MS=5000
  DELAY_JITTER_MS=2000
  

• Wait 60+ seconds before retrying

Need to Re-login

• Delete session:

  rm telegram_session.session
  

• Run again, you'll be prompted for verification code

Documentation

• Full project README: README.md
• Configuration guide: .env.example
• Exclude list example: exclude_list.json.example