bellingcat / telegram-phone-number-checker

Check if phone numbers are connected to Telegram accounts.

telegram-phone-number-checker

Python tool/script to check if phone numbers are connected to Telegram accounts. Retrieving username, name, and IDs where available.

Installation

You can install this tool directly from the official pypi release.

pip install telegram-phone-number-checker

You can also install it and run it directly from GitHub as a script.

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:

# single phone number
telegram-phone-number-checker --phone-numbers [phone]

# multiple phone numbers
telegram-phone-number-checker --phone-numbers [phone],[phone],[phone]

# 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 [phone]

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.

# 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 to manage dependencies. You can install dependencies via poetry, or use the up-to-date requirements.txt file.

# install poetry if you haven't already
pip install poetry

# with poetry
poetry install

# with pip
pip install -r requirements.txt

You can then run it with any of these:

# with poetry
poetry run telegram-phone-number-checker

# with pip installation
python3 telegram_phone_number_checker/main.py

Generating requirements.txt & requirements-dev.txt

Poetry is used to generate both of these files. requirements.txt contains only those dependencies necessary for running the CLI. requirements-dev.txt contains all dependencies including those used for running tests, linters, etc.

To generate requirements.txt:

poetry export --output=requirements.txt --without-urls

To generate requirements-dev.txt:

poetry export --output=requirements-dev.txt --without-urls --with=dev

💡 --without-urls is for users who install from their own private package repository instead of pypi.org

telegram-phone-number-checker's Issues

Add formatting, linting, static type checking

I'd like to add black, flake8, and mypy to the developer tools.

I'd be happy to do this work if this is something project maintainers want. I would start by opening a single PR that adds black and formats files.

I do worry that flake8 and mypy would decrease newer contributors willingness/comfort contributing to the codebase - but it also seems like all active developers are experienced. So not sure if this will be a problem.

Can we use this to detect banned number

Hello sir,
How to check weather number banned by telegram?

What is the following

[email protected]

TypeError: Cannot cast NoneType to any kind of Peer..

Hey,
I've some trouble using the checker. Some of my phonenumbers working fine. But some throw the following error:
error": "TypeError: Cannot cast NoneType to any kind of Peer.. --> The error might have occurred due to the inability to delete the phone_number='[phone]' from the contact list."

I can't find the problem, why this happens random to some phonenumbers. If a number works, it works every time I try, same with numbers which didn't works.

Thanks for help.

Return richer information about accounts

At the moment, the tool makes the id, username, first_name, last_name fields available for each account that is successfully found.

Telethon returns several more fields associated with a User, as detailed in their api.

Some of these fields (fake, scam, premium,verified, etc...) look like they could be of interest to researchers. This may need some research, as it is unclear how widely these fields are used and if they are likely to be accurate.

It would be good if useful fields could be identified and returned to the tool user.

Help text doesn't explain .env for API credentials

Now that this can be installed from pypi directly, it would be good if the helptext (accessed with telegram-phone-number-checker --help) provided an explanation of the .env file for credential storage (as in README.md).

REST API

Hi!

Your project is awesome)

Can you create a branch where this app will be format to small server with one route, where I can check number
If you want try to compare with Docker

I can host this project on my server for all peoples)

Confusing docstring for validate_users

I find the docstring of the function validate_users() confusing. It mentions get_api_response(), but there is no such function. The description of the return value is confusing as well: "the first user name and the last user name". Should it be "the first name, last name and username"?

def validate_users(client, phone_numbers):
    '''
    The function uses the get_api_response function to first check if the user exists and if it does, then it returns the first user name and the last user name.
    '''

Pypi package it!

It would be great to leverage this into a pypi package that would simplify it's installation and usage.

Add command line arguments for script inputs

I recommend using argparse so that users do not need to edit hardcoded values in the script.