telegram-phone-number-checker answers one narrow question about a number

One question, one Telegram session, one JSON file

The tool does exactly what its name says: given a phone number or a Telegram username, it asks Telegram whether an account exists and reports the username, display name and ID when they are available. There is no enrichment, no OSINT graph and no cross-platform search. Everything it knows comes from one Telegram API session.

That narrowness is the design. It is built on Telethon, the Python MTProto client, and the whole CLI is a thin layer over it. Running it produces console output and a results.json file in the working directory, and passing --output with your own filename redirects that file.

# single phone number
telegram-phone-number-checker --phone-numbers +1234567890

The package installs a console entry point named telegram-phone-number-checker that maps to telegram_phone_number_checker.main:main_entrypoint, so the command you type is the same on every platform where pip can install it. Because it is a Click application, running it with no arguments drops into an interactive mode that prompts for the same values.

Credentials come from a developer account you have to create first

There is no API key bundled with the tool. You need API_ID and API_HASH from a Telegram developer account created at my.telegram.org, plus the phone number of a Telegram account that has an active number. The README is explicit that the account requirement is a real account with a working number, not a placeholder.

The three values can come from three places, in decreasing order of convenience. Put them in a .env file:

API_ID=
API_HASH=
PHONE_NUMBER=

Or pass them on the command line, which also overwrites what is in .env:

telegram-phone-number-checker --api-id YOUR_API_KEY --api-hash YOUR_API_HASH --api-phone-number YOUR_PHONE_NUMBER --phone-numbers +1234567890

Or answer the prompts when the tool asks. The README notes that the file is optional for that reason. python-dotenv is a declared dependency, so the .env route needs no extra package.

Credentials in a .env file are credentials in plaintext. If you script this, keep the file out of version control and out of shared storage.

The account and IP warning is the operational constraint

The README opens with a warning that is the single most important line in the document: it advises against using a personal account for automations, because Telegram may block it, and it states that a fresh account works best from residential IPs rather than known VPN IPs.

That framing tells you what kind of tool this is. It authenticates as an ordinary client and issues many lookups, which is exactly the pattern Telegram's abuse controls target. A blocked account is not an error the tool can retry around; it ends the session.

The proxy support added in the 1.2.2 release exists for the same reason and the README says so explicitly: if you need to avoid a known VPN or datacenter IP, install the optional extra and pass --proxy. The URL scheme carries the credentials.

pip install telegram-phone-number-checker[proxy]

telegram-phone-number-checker --phone-numbers +1234567890 --proxy socks5://user:[email protected]:1080

SOCKS5, SOCKS4 and HTTP proxies are all named as supported, and PySocks sits behind the proxy extra in pyproject.toml. The same value can come from a PROXY environment variable or from .env instead of the command line, which is the better option in CI. Understand your trade here: routing through a proxy moves the reputation problem from your IP to the proxy.

Two result shapes and the message that means two things

For each number or username, the README enumerates the responses you can expect. A hit returns the Telegram username, name and ID connected to that number. A specific negative says 'no username detected', which means the number was used to create an account but the person never chose a username, an optional field on Telegram.

Then comes the response that makes or breaks the tool: 'ERROR: no response, the user does not exist or has blocked contact adding.' The README itself lists the two reasons behind that single message. Either the number was never used to create a Telegram account, or it is linked to an account whose owner restricted discovery by phone number.

Those cases are indistinguishable from the output. For an investigative workflow that is the central fact, not a footnote. A researcher who needs to know whether someone is hiding a Telegram account will get the same line as someone whose subject simply has no Telegram presence, and nothing in the JSON separates them. Username searches add one more variant: the name may exist but belong to a channel or supergroup rather than a user, in which case the tool reports that the target is a group and states it searches user accounts only.

Username searches accept the same comma-separated form, and can be combined with phone numbers in one run.

telegram-phone-number-checker --usernames john,jane --download-profile-photos

The --download-profile-photos flag pulls profile images for the resolved accounts.

Python 3.9 floor, Click CLI, Telethon under the hood

pyproject.toml pins the floor at python = ^3.9 and pins the interesting dependencies tightly: telethon ^1.33.1, click ^8.1.7, anyio ^4.2.0, pyaes ^1.6.1, rsa ^4.9 and pyasn1 ^0.5.1. The cryptography stack is the MTProto one, which is why pyaes, rsa and pyasn1 appear in a Telegram client at all.

Development installs are managed with poetry. The documented options are either poetry install or pip install -r requirements.txt, and requirements.txt is generated with hashes, so the pip route is reproducible in the sense that matters for an investigation record.

pip install poetry

# with poetry
poetry install

Tests run under pytest with pythonpath set to the project root, and the dev group carries black, isort and pytest 8. Version 1.2.2 is what pyproject.toml declares, matching the release tagged on 2026-08-17, whose title is "username and proxy support". That release line is the one to read the docs against, since both --usernames and --proxy arrived with it.

What it does not do, and what to use instead

The obvious limit is coverage. This queries Telegram and nothing else. It does not correlate the result with other platforms, does not check whether a number is registered anywhere else, does not resolve the person's name, and does not archive anything. There is no batch file input documented beyond comma-separated arguments on the command line, which matters if you have thousands of numbers rather than ten.

The alternative for the same narrow goal is to write the query directly against Telethon yourself. That buys you control over batching, rate limiting, retry policy and structured logging, at the cost of the CLI and its output format. For a handful of numbers the packaged tool wins; for a systematic sweep or an evidence trail, a purpose-built script is the honest choice.

For anything beyond the phone-number question, this is the wrong tool by construction. A Telegram account existing is not a fact about a person, and the error taxonomy above is the reason to treat even that fact carefully.

MIT, actively tagged, one maintainer shop

Licensing is MIT, stated in pyproject.toml and in the LICENSE file, subject to the conditions in the MIT License.

The project is not archived and the last push was on 2026-08-17, the same day as the 1.2.2 release. Before that, 1.2.1 dates from 2024-06-24 and 1.1.0 from 2024-03-05, so releases come in occasional batches rather than on a schedule.

It comes from Bellingcat, an investigative outlet, and the README points to their Discord, their open-source research notebooks on Colab and the project page on PyPI. That matters for how you use the output: this is a tool built for people documenting real events, and its own warning about personal accounts is part of that context. Treat results.json as evidence to be verified, not as a finding.

Editorial conclusion

Adopt telegram-phone-number-checker if your work needs a reproducible phone-number-to-Telegram-account step with JSON output you can diff across runs, and you can supply a throwaway Telegram session plus credentials from my.telegram.org. Do not adopt it as an identity proof: the tool itself documents that a blocked contact and an unused number produce the same message, so a negative result proves nothing about the person. Before a first run, decide on the account and IP story the README warns about, because a blocked session ends the query, then confirm that pip install telegram-phone-number-checker gives you version 1.2.2 with --proxy available only after installing the proxy extra. MIT licensing and the Click and Telethon stack make it safe to fork.

Frequently asked questions

Official sources

1. bellingcat/telegram-phone-number-checker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases