{"id":26236912,"url":"https://github.com/estebanpdl/telegram-tracker","last_synced_at":"2025-04-06T03:05:20.483Z","repository":{"id":41571979,"uuid":"478432944","full_name":"estebanpdl/telegram-tracker","owner":"estebanpdl","description":"The package connects to Telegram's API to generate JSON files containing data for channels, including information and posts. It allows you to search for specific channels or a set of channels provided in a text file, with one channel per line.","archived":false,"fork":false,"pushed_at":"2024-08-08T19:10:56.000Z","size":25,"stargazers_count":357,"open_issues_count":5,"forks_count":59,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T02:03:37.931Z","etag":null,"topics":["open-source","osint","osint-python","python","python3","telegram-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/estebanpdl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-06T06:33:10.000Z","updated_at":"2025-03-23T23:00:19.000Z","dependencies_parsed_at":"2023-11-22T14:35:46.050Z","dependency_job_id":"b86b4582-acde-484b-8e16-df5b3586592e","html_url":"https://github.com/estebanpdl/telegram-tracker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/estebanpdl%2Ftelegram-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/estebanpdl%2Ftelegram-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/estebanpdl%2Ftelegram-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/estebanpdl%2Ftelegram-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/estebanpdl","download_url":"https://codeload.github.com/estebanpdl/telegram-tracker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427005,"owners_count":20937200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["open-source","osint","osint-python","python","python3","telegram-api"],"created_at":"2025-03-13T04:19:57.735Z","updated_at":"2025-04-06T03:05:20.465Z","avatar_url":"https://github.com/estebanpdl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# **Telegram-API**: `a Python-based open-source tool for Telegram`\n\n---\n\n[![GitHub forks](https://img.shields.io/github/forks/estebanpdl/telegram-tracker.svg?style=social\u0026label=Fork\u0026maxAge=2592000)](https://GitHub.com/estebanpdl/telegram-tracker/network/)\n[![GitHub stars](https://img.shields.io/github/stars/estebanpdl/telegram-tracker?style=social)](https://github.com/estebanpdl/telegram-tracker/stargazers)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/estebanpdl/telegram-tracker/blob/main/LICENCE)\n[![Open Source](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://twitter.com/estebanpdl)\n[![Made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)\n[![Twitter estebanpdl](https://badgen.net/badge/icon/twitter?icon=twitter\u0026label)](https://twitter.com/estebanpdl)\n\n---\n\u003c/div\u003e\n\n## Overview\n\nThis tool connects to Telegram's API. It generates JSON files containing channel's data, including channel's information and posts. You can search for a specific channel, or a set of channels provided in a text file (one channel per line.)\n\nFiles are saved by default in a folder called *output/data*. These folders are created by the script. You can also give a specific output directory to store collected data.\n\n**Software required**\n\n* [Python 3.x](https://www.python.org/)\n* [Telegram API credentials](https://my.telegram.org/auth?to=apps)\n\t+ Telegram account\n\t+ App `api_id`\n\t+ App `api_hash`\n\n**Python required libraries**\n\n* [Telethon](https://docs.telethon.dev/en/stable/)\n* [Pandas](https://pandas.pydata.org/)\n* [Openpyxl](https://openpyxl.readthedocs.io/en/stable/)\n* [tqdm](https://tqdm.github.io/)\n* [Networkx](https://networkx.org/)\n* [Matplotlib](https://matplotlib.org/)\n* [Louvain Community Detection](https://github.com/taynaud/python-louvain)\n\n\nInstalling\n----------\n\n- **Via git clone**\n\n```\ngit clone https://github.com/estebanpdl/telegram-api.git\n```\n\nThis will create a directory called `telegram-tracker` which contains the Python scripts. Cloning allows you to easily upgrade and switch between available releases.\n\n- **From the github download button**\n\nDownload the ZIP file from github and use your favorite zip utility to unpack the file `telegram-tracker.zip` on your preferred location.\n\n**After cloning or downloding the repository, install the libraries from `requirements.txt`.**\n\n```\npip install -r requirements.txt\n```\n\nor\n\n```\npip3 install -r requirements.txt\n```\n\n**Once you obtain an API ID and API hash on my.telegram.org, populate the `config/config.ini` file with the described values.**\n\n```ini\n\n[Telegram API credentials]\napi_id = api_id\napi_hash = api_hash\nphone = phone\n```\n\n*Note: Your phone must be included to authenticate for the first time. Use the format +\\\u003ccode\u003e\\\u003cnumber\u003e (e.g., +19876543210). Telegram API will send you a code via Telegram app that you will need to include.*\n\n\u003cbr /\u003e\n\n---\n\n# Example usage\n\n## `main.py`\n\nThis Python script will connect to Telegram's API and handle your API request.\n\n### Options\n\n* `--telegram-channel` Specifies Telegram Channel to download data from.\n* `--batch-file` File containing Telegram Channels to download data from, one channel per line.\n* `--limit-download-to-channel-metadata` Will collect channels metadata only, not channel's messages. (default = False)\n* `--output, -o` Specifies a folder to save collected data. If not given, script will generate a default folder called `./output/data`\n* `--min-id` Specifies the offset id. This will update Telegram data with new posts.\n\n\u003cbr /\u003e\n\n### Structure of output data\n\n```\n├──🗂 output\n|   └──🗂 data\n|   \t└──🗂 \u003cchannel_name\u003e\n|   \t\t└──\u003cchannel_name\u003e.json\n|   \t\t└──\u003cchannel_name\u003e_messages.json\n|   \t└──chats.txt // TM channels, groups, or users' IDs found in data.\n|   \t└──collected_chats.csv // TM channels or groups found in data (e.g., forwards)\n|   \t└──collected_chats.xlsx // TM channels or groups found in data (e.g., forwards)\n|   \t└──counter.csv // TM channels, groups or users found in data (e.g., forwards)\n|   \t└──user_exceptions.txt // From collected_chats, these are mostly TM users' which \n|\t\t\t\t\t\t\t\t\tmetadata was not possible to retrieve via the API\n|   \t└──msgs_dataset.csv // Posts and messages from the requested channels\n```\n\n\u003cbr /\u003e\n\n## **Examples**\n\n\u003cbr /\u003e\n\n### **Basic request**\n\n```\npython main.py --telegram-channel channelname`\n```\n\n**Expected output**\n\n- Files of collected channels:\n\t- chats.txt\n\t- collected_chats.csv\n\t- user_exceptions.txt\n\t- counter.csv\n- A new folder: *\u003cchannel_name\u003e* containing\n\t- A JSON file containing channel's profile metadata\n\t- A JSON file containing posts from the requested channel\n\n\u003cbr /\u003e\n\n### **Request using a text file containing a set of channels**\n\n```\npython main.py --batch-file './path/to/channels_text_file.txt'\n```\n\n**Expected output**\n\n- Files of collected channels:\n\t- chats.txt\n\t- collected_chats.csv\n\t- user_exceptions.txt\n\t- counter.csv\n- New folders - based on the number of requested channels: *\u003cchannel_name\u003e* containing\n\t- A JSON file containing channel's profile metadata\n\t- A JSON file containing posts from the requested channel\n\nThese examples will retrieve all posts available through the API from the requested channel. If you want to collect channel's information only, without posts, you can run:\n\n\u003cbr /\u003e\n\n### **Limit download to channel's metadata only**\n\n```\npython main.py --telegram-channel channelname --limit-download-to-channel-metadata\n```\n\nor, using a set of telegram channels via a text file:\n\n```\npython main.py --batch-file './path/to/channels_text_file.txt' --limit-download-to-channel-metadata\n```\n\n\u003cbr /\u003e\n\n### **Updating channel's data**\n\nIf you want to collect new messages from one channel, you need to identify the message ID from the last post. Once you identify the id, run:\n\n```\npython main.py --telegram-channel channelname --min-id 12345\n```\n\n**Expected output**\n\n- Files of collected channels:\n\t- chats.txt\n\t- collected_chats.csv\n\t- user_exceptions.txt\n\t- counter.csv\n- A new folder: *\u003cchannel_name\u003e* containing\n\t- A JSON file containing channel's profile metadata\n\t- A JSON file containing posts from the requested channel\n\n\u003cbr /\u003e\n\n### **Specify output folder**\n\nThe script allows you to specify a specific output directory to save collected data. The sxcript will create those folders in case do not exist.\n\n```\npython main.py --telegram-channel channelname --output ./path/to/chosen/directory`\n```\n\nThe expected output is the same a described above but data will be save using the chosen directory.\n\n\u003cbr /\u003e\n\n---\n\n## `build-datasets.py`\n\nThis Python script reads the collected files and creates a new dataset containing messages from the requested channels. By default, the created dataset will be located in the `output` folder.\n\nIf you provided a specific directory to save collected data, you need to provide the same path to use this script.\n\n### Options\n\n* `--data-path` Path were data is located. Will use `./output/data` if not given.\n\nIf a specific directory was not provided in `main.py`, run:\n\n```\npython build-datasets.py\n```\n\nIf you provided a specific directory using the option `--output` in `main.py`, run:\n\n```\npython build-datasets.py --data-path ./path/to/chosen/directory\n```\n\nThese option will create the above-mentioned dataset: `msgs_dataset.csv`, a file containing posts and messages from the requested channels.\n\n\u003cbr /\u003e\n\n---\n\n## `channels-to-network.py`\n\nThis Python script builds a network graph. By default, the file will be located in the `output` folder. The script also saves a preliminary graph: `network.png` using the modules matplotlib, networkx, and python-louvain, which implements community detection. You can import the GEFX Graph File using different softwares, including Gephi.\n\n### Options\n\n* `--data-path` Path were data is located. Will use `./output/data` if not given.\n\nIf a specific directory was not provided in `main.py`, run:\n\n```\npython channels-to-network.py\n```\n\nIf you provided a specific directory using the option `--output` in `main.py`, run:\n\n```\npython channels-to-network.py --data-path ./path/to/chosen/directory\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festebanpdl%2Ftelegram-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Festebanpdl%2Ftelegram-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festebanpdl%2Ftelegram-tracker/lists"}