Syncing Telegram Group Members to a CSV

Alright, let’s talk about a workflow that saved me a surprising amount of time. I manage a few internal technical groups at TechResolve, and for a while, I was manually cross-referencing member lists with our internal directory for compliance and onboarding checks. It was tedious and error-prone. I realized I was wasting a good couple of hours every week on something a simple script could automate.

This guide is the result. We’re going to build a Python script that pulls the member list from any Telegram group you administer and syncs it neatly into a CSV file. It’s a classic DevOps win: automate the boring stuff so you can focus on the real engineering challenges.

Prerequisites

Before we dive in, make sure you have these things ready. This will make the whole process much smoother.

• Python 3.x installed on your system.
• A Telegram account that is an administrator in the target group. This is non-negotiable; you need admin rights to see the full member list.
• Telegram API Credentials (api_id and api_hash). If you don’t have these, you can get them from my.telegram.org by creating a new “app”. Just give it a simple name; the details aren’t critical for this script.
• The necessary Python libraries. You’ll need telethon for the Telegram API interaction and python-dotenv to manage our credentials safely. I usually install these using pip, Python’s package manager.

The Guide: Step-by-Step

Step 1: Set Up Your Project Environment

Every good project needs a clean workspace. I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Let’s jump straight to the important parts.

First, create a file named config.env in your project directory. This is where we’ll store our sensitive credentials instead of hardcoding them into the script—a practice I insist on for all my production setups.

Your `config.env` file should look like this:

API_ID="YOUR_API_ID_HERE"
API_HASH="YOUR_API_HASH_HERE"
SESSION_NAME="my_telegram_session"
TARGET_GROUP_ID=-1001234567890 # Example ID, replace with yours

A quick note on the `TARGET_GROUP_ID`: For public groups, you can use the `@username`. For private groups, you’ll need the numerical ID. You can get this by using a bot like `@userinfobot`, adding it to your group temporarily, and it will reveal the chat ID. Remember that private group IDs typically start with `-100`.

Step 2: The Python Script

Now for the fun part. Create a Python file, let’s call it `sync_members.py`. We’re going to build this out piece by piece.

First, let’s handle the imports and load our configuration. We’ll use the `dotenv` library to read from our `config.env` file and `os` to access those values. The `csv` library will, of course, handle writing our data.

import os
import csv
from dotenv import load_dotenv
from telethon.sync import TelegramClient
from telethon.tl.types import ChannelParticipantsSearch
from telethon.errors.rpcerrorlist import ChatAdminRequiredError

# Load environment variables from config.env
load_dotenv('config.env')

# Read credentials from environment
API_ID = os.getenv('API_ID')
API_HASH = os.getenv('API_HASH')
SESSION_NAME = os.getenv('SESSION_NAME')
TARGET_GROUP_ID = int(os.getenv('TARGET_GROUP_ID')) # Convert to integer
OUTPUT_FILE = 'telegram_members.csv'

# Define the headers for our CSV file
CSV_HEADER = ['user_id', 'first_name', 'last_name', 'username', 'is_bot']

Next, we’ll write the main logic. I’m wrapping this in an `async` function because `telethon` is an asynchronous library, which makes it incredibly efficient at handling network requests.

The script will connect to Telegram, find our target group, and then loop through every single member, writing their details to our CSV file.

async def main():
    # We use a 'with' statement for proper session management
    async with TelegramClient(SESSION_NAME, API_ID, API_HASH) as client:
        print("Client created. Fetching group members...")

        try:
            # Get the entity for our target group
            group_entity = await client.get_entity(TARGET_GROUP_ID)
            all_participants = []

            # client.iter_participants is the most efficient way to get all members
            async for user in client.iter_participants(group_entity, limit=None):
                # We only care about users, not channels or other entities
                if not user.deleted:
                    all_participants.append({
                        'user_id': user.id,
                        'first_name': user.first_name,
                        'last_name': user.last_name,
                        'username': user.username,
                        'is_bot': user.bot
                    })
            
            print(f"Found {len(all_participants)} members. Writing to {OUTPUT_FILE}...")

            # Now, write the data to the CSV file
            with open(OUTPUT_FILE, 'w', newline='', encoding='utf-8') as f:
                writer = csv.DictWriter(f, fieldnames=CSV_HEADER)
                writer.writeheader()
                for member in all_participants:
                    # Sanitize data before writing
                    writer.writerow({
                        'user_id': member['user_id'],
                        'first_name': member['first_name'] or '',
                        'last_name': member['last_name'] or '',
                        'username': member['username'] or '',
                        'is_bot': member['is_bot']
                    })
            
            print("Successfully synced group members to CSV.")

        except ChatAdminRequiredError:
            print("Error: You must be an admin in the target group to fetch members.")
            return # Exit the function gracefully
        except Exception as e:
            print(f"An unexpected error occurred: {e}")
            return # Exit the function gracefully

# This is the standard way to run an async main function
if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Pro Tip: Notice the `limit=None` in `client.iter_participants`. This is crucial. By default, Telethon might only fetch a small batch. Setting the limit to `None` tells it to paginate through the entire member list, no matter how large the group is. It’s surprisingly efficient and handles rate-limiting automatically.

Step 3: Running and Automating the Sync

To run the script, you just execute it from your terminal. I’m assuming your current directory is where the script and `config.env` are located.

The first time you run `python3 sync_members.py`, Telethon will prompt you for your phone number, a login code sent to your Telegram app, and possibly your two-factor authentication password. This creates a `.session` file (in our case, `my_telegram_session.session`). This file keeps you logged in, so you won’t have to do this again.

For automation, a simple cron job works wonders. I usually set mine to run once a week or once a day, depending on the need. To run it every Monday at 2 AM, the cron entry would look like this:

`0 2 * * 1 python3 sync_members.py`

This gives me a fresh member list for our weekly reporting without me ever having to think about it.

Common Pitfalls

Here’s where I’ve stumbled in the past, so you don’t have to:

• Permissions Error (`ChatAdminRequiredError`): This is the most common issue. It means exactly what it says: the account associated with your API keys is not an administrator in the target group. Double-check your permissions in the Telegram app.
• Incorrect Group ID: If the script can’t find the group, you might have the wrong ID. For private groups, ensure the ID is correct and starts with `-100`. For public groups, try using the `t.me/` link instead of just the `@username`.
• The `.session` File: This file is your active login token. Treat it like a password. Never commit it to a public Git repository. Add `*.session` to your `.gitignore` file immediately. If it gets compromised, someone could potentially access your Telegram account.

Conclusion

And there you have it. You’ve now got a robust, automated workflow for syncing your Telegram group members to a CSV. This isn’t just a convenience; it’s a building block. You can now feed this data into other systems, generate reports, or integrate it with other monitoring tools. It’s a small script, but in my experience, these are the kinds of focused automations that have the biggest impact on our daily operations. Happy scripting

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions