mirror of
https://github.com/bellingcat/telegram-phone-number-checker.git
synced 2026-06-12 05:18:29 +03:00
93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# telegram-phone-number-checker
|
|
|
|
Python tool/script toc heck if phone numbers are connected to Telegram accounts.
|
|
|
|
## Installation
|
|
|
|
[](https://pypi.org/project/telegram-phone-number-checker/)
|
|
|
|
You can install this tool directly from the [official pypi release](https://pypi.org/project/telegram-phone-number-checker/).
|
|
|
|
```bash
|
|
pip install telegram-phone-number-checker
|
|
```
|
|
|
|
You can also install it and run it directly from github as a script.
|
|
```bash
|
|
git clone https://github.com/bellingcat/telegram-phone-number-checker
|
|
cd telegram-phone-number-checker
|
|
pip install -r requirements.txt
|
|
python telegram-phone-number-checker/main.py
|
|
```
|
|
|
|
## Requirements
|
|
To run it, you need:
|
|
|
|
1. A Telegram account with an active phone number;
|
|
2. Telegram `API_ID` and `API_HASH`, which you can get by creating a developers account at https://my.telegram.org/. Place these values in a `.env` file, along with the phone number of your Telegram account:
|
|
|
|
```
|
|
API_ID=
|
|
API_HASH=
|
|
PHONE_NUMBER=
|
|
```
|
|
If you don't create this file, you can also provide these 3 values when calling the tool, or even be prompted for them interactively.
|
|
|
|
## Usage
|
|
The tool accepts a comma-separated list of phone numbers to check, you can pass this when you call the tool, or interactively.
|
|
|
|
See the examples below:
|
|
|
|
```bash
|
|
# single phone number
|
|
telegram-phone-number-checker --phone-numbers +1234567890
|
|
|
|
# multiple phone numbers
|
|
telegram-phone-number-checker --phone-numbers +1234567890,+9876543210,+111111111
|
|
|
|
# interactive version, you will be prompted for the phone-numbers
|
|
telegram-phone-number-checker
|
|
|
|
# overwrite the telegram API keys in .env (or if no .env is found)
|
|
telegram-phone-number-checker --api-id YOUR_API_KEY --api-hash YOUR_API_HASH --api-phone-number YOUR_PHONE_NUMBER --phone-numbers +1234567890
|
|
```
|
|
|
|
The result will be written to the console but also written as JSON to a `results.json` file, you can write it to another file by adding `--output your_filename.json` to the command.
|
|
|
|
For each phone number, you can expect the following possible responses:
|
|
|
|
1. If available, you will receive the Telegram Username,Name, and ID that are connected with this number.
|
|
2. 'no username detected'. This means that it looks like the number was used to create a Telegram account but the user did not choose a Telegram Username. It is optional to create a Username on Telegram.
|
|
3. 'ERROR: no response, the user does not exist or has blocked contact adding.': There can be several reasons for this response. Either the phone number has not been used to create a Telegram account. Or: The phone number is connected to a Telegram account but the user has restricted the option to find him/her via the phone number.
|
|
4. Or: another error occurred.
|
|
|
|
|
|
## Development
|
|
This section describes how to install the project in order to run it locally, for example if you want to build new features.
|
|
|
|
```bash
|
|
# clone the code
|
|
git clone https://github.com/bellingcat/telegram-phone-number-checker
|
|
|
|
# move into the project's folder
|
|
cd telegram-phone-number-checker
|
|
```
|
|
|
|
This project uses [poetry](https://python-poetry.org/) to manage dependencies. You can install dependencies via poetry, or use the up-to-date [requirements.txt](requirements.txt) file.
|
|
|
|
```bash
|
|
# with poetry
|
|
poetry install
|
|
|
|
# with pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
You can then run it with any of these:
|
|
```bash
|
|
# with poetry
|
|
poetry run python3 telegram_phone_number_checker/main.py
|
|
|
|
# with pip installation
|
|
python3 telegram_phone_number_checker/main.py
|
|
``` |