# Telegram Exporter

> telegram-exporter

- Skill: `0xdeval/telegram-exporter` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 0xdeval/telegram-exporter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0xdeval/telegram-exporter/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 0xdeval (https://skillmd.com/u/0xdeval)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/0xdeval/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`
```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:

```json
[
  "@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`