OSINT Tool Tuesday - Telegram Phone Number Checker

Learn how to use Telegram Phone Number Checker for OSINT investigations

👋 Welcome to OSINT Tool Tuesday! This week, we're delving into Telegram Phone Number Checker, an OSINT tool designed for investigating phone numbers associated with Telegram accounts.

🚨 This tool has been added to the OSINT Resources for Phone Numbers page on The OSINT Newsletter for easy reference later. That list serves as a roadmap for new tutorials in the future. If there are any tools you’d like to see added to the list and covered, please reach out jake@osint.news with details.

---

Telegram Phone Number Checker

Telegram Phone Number Checker is a valuable resource for open-source intelligence (OSINT) analysts. It allows you to identify a Telegram user by their phone number. Using this tool, you’ll gather the username, display name, and other valuable information associated with the target phone number on Telegram.

🗒️ It requires you to use the Telegram API; however, this tool makes configuration quite easy.

🎩 H/T: Bellingcat

This tool, combined with other tools like Telegram Nearby Map, allows you to gather valuable information not indexed by search engines.

In this tutorial, we’ll walk through setup, usage, and use cases for Telegram Phone Number Checker and how you can pivot from this information to expand the scope of your investigation.

⬇️ Let’s get started.

---

Setup

First, we’re going to go over the traditional way to install this project from GitHub. Later, we’ll go through an easier way to install this script so we can use it globally.

To get started, use git to clone the repository to your device. You can do so by entering the following command in your terminal.

git clone https://github.com/bellingcat/telegram-phone-number-checker.git

🗒️ If you don’t have git installed on your device, use this guide to install it.

Once you have the repository cloned locally, use the following command to open the directory in your terminal.

cd telegram-phone-number-checker

That should open that directory in your terminal. To verify, enter the “ls” command to list the files in the directory you’re in. If successful, it should look something like this.

jakecreps@Macbook telegram-phone-number-checker % ls
LICENSE				requirements-dev.txt
README.md			requirements.txt
poetry.lock			telegram_phone_number_checker
pyproject.toml			tests

Now that you have the project downloaded locally, we’ll need to install the dependencies.

You’ll notice there’s a requirements.txt file in the directory. Using this file, we’ll use the following command to install the requirements.

pip install -r requirements.txt

🗒️ If you’re new to command line tools, this might throw an error and say something like “pip isn’t installed”. Since every device is different, I recommend using ChatGPT to debug to resolve the issue.

Obtaining a Telegram API Key

This tool requires a Telegram API key to work. Getting a Telegram API key is free. To get started, head to Telegram and create an account with an active phone number if you don’t already have one.

🗒️ I recommend using a burner phone number; however, your personal device is okay. Just remember that someone could use this tool with your phone number.

Once you’ve created an account, head to the apps section. Here you can create a new app that will provide you with an API key and hash.

Once you’ve successfully created an app, it should look something like this (minus the blacked-out areas).

The App api_id and App api_hash is what we’ll use to finalize the configuration of telegram-phone-number-checker.

Applying the API key and hash

You can test the app by using the following commands.

cd telegram-phone-number-checker/telegram-phone-number-checker # To open the directory and the folder the main script is in
python main.py # To run the script

One thing you will notice is it will ask you for your app_id and app_hash right away. If you use this tool frequently, it’ll ask you for these every time. This can be time-consuming and make you not want to use the tool.

In order to prevent this from happening every time, there’s an instruction on the GitHub ReadMe that reads:

Place these values in a .env file, along with the phone number of your Telegram account:

API_ID=
API_HASH=
PHONE_NUMBER=

This can be a confusing step for those who aren’t familiar with .env files. In order to make this simple, here’s all you need to know.

If you’re using Windows, enter the following command when in the same directory as main.py.

echo API_ID=your_api_id >> .env
echo API_HASH=your_api_hash >> .env
echo PHONE_NUMBER=your_phone_number >> .env

🗒️ Replace your_api_id with your id from Telegram; likewise for your_api_hash; finally, replace your_phone_number with the phone number you registered on Telegram.

If you’re using Mac/Linux, enter the following command when in the same directory as main.py. The only difference is the quotes.

echo "API_ID=your_api_id" >> .env
echo "API_HASH=your_api_hash" >> .env
echo "PHONE_NUMBER=your_phone_number" >> .env

This should create your .env file, allowing telegram-phone-number-checker to automatically apply your credentials instead of prompting you.

If you run main.py again, it should apply these credentials automatically.

🗒️ You may be prompted to enter a code from Telegram. This won’t get sent via SMS. You’ll have to open the Telegram app to get the code.

If successful, you should see something like this.

jakecreps@Macbook telegram_phone_number_checker % python main.py 
Logging in...Done.
Enter the phone numbers to check, separated by commas: 

⬇️ Now, let’s move into usage.

---

Usage

Telegram-phone-number-checker allows you to search by a single phone number or a list of phone numbers. To input a single phone number, enter the following command and replace the placeholder phone number with the phone number from your investigation.

python main.py --phone-numbers +1234567890

🗒️ Don’t forget the country code.