notebooks/bellingcat/telegram-phone-number-checker.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Telegram Phone Number Checker\n",
    "\n",
    "<a href=\"https://www.bellingcat.com\"><img alt=\"Bellingcat logo: Discover Bellingcat\" src=\"https://img.shields.io/badge/Discover%20Bellingcat-%20?style=for-the-badge&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAYCAYAAADKx8xXAAABhGlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw0AcxV9TS0UqDnZQEcxQneyiIo6likWwUNoKrTqYXPoFTRqSFBdHwbXg4Mdi1cHFWVcHV0EQ%2FABxdnBSdJES%2F5cUWsR4cNyPd%2Fced%2B8AoVllqtkTA1TNMtKJuJjLr4rBVwQwhhBEDEvM1JOZxSw8x9c9fHy9i%2FIs73N%2Fjn6lYDLAJxLHmG5YxBvEs5uWznmfOMzKkkJ8Tjxp0AWJH7kuu%2FzGueSwwDPDRjY9TxwmFktdLHcxKxsq8QxxRFE1yhdyLiuctzir1Tpr35O%2FMFTQVjJcpzmKBJaQRIo6klFHBVVYiNKqkWIiTftxD%2F%2BI40%2BRSyZXBYwcC6hBheT4wf%2Fgd7dmcXrKTQrFgcCLbX%2BMA8FdoNWw7e9j226dAP5n4Err%2BGtNYO6T9EZHixwBA9vAxXVHk%2FeAyx1g6EmXDMmR%2FDSFYhF4P6NvygODt0Dfmttbex%2BnD0CWulq%2BAQ4OgYkSZa97vLu3u7d%2Fz7T7%2BwHEU3LHAa%2FQ6gAAAAZiS0dEAAAAAAAA%2BUO7fwAAAAlwSFlzAAAuIwAALiMBeKU%2FdgAAAAd0SU1FB%2BgFHwwiMH4odB4AAAAZdEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVBXgQ4XAAAA50lEQVQ4y82SvWpCQRCFz25ERSJiCNqlUiS1b5AuEEiZIq1NOsGXCKms0wXSp9T6dskDiFikyiPc%2FrMZyf3FXSGQ0%2BzuzPl2ZoeVKgQ0gQ2wBVpVHlcDkjM5V%2FJ5nag6sJ%2FZX%2Bh%2FC7gEhqeAFKf7p1M9aB3b5oN1OomB7g1axUBPBr3GQHODHmOgqUF3MZAzKI2d4LWBV4H%2BMXDuJd1a7Cew1k7SwksaHC4LqNaw7aeX9GWHXkC1G1sTAS17Y3Kk2lnp4wNLiz0DrgLq8qt2MfmSSabAO%2FBBXp26dtrADPjOmN%2BAUdG7B3cE61l5hOZiAAAAAElFTkSuQmCC&logoColor=%23fff&color=%23000\"></a><!--\n",
    "--><a href=\"https://discord.gg/bellingcat\"><img alt=\"Discord logo: Join our community\" src=\"https://img.shields.io/badge/Join%20our%20community-%20?style=for-the-badge&logo=discord&logoColor=%23fff&color=%235865F2\"></a><!--\n",
    "--><a href=\"https://github.com/bellingcat/telegram-phone-number-checker\"><img alt=\"Github logo: Explore the code\" src=\"https://img.shields.io/badge/Explore%20the%20code-%20?style=for-the-badge&logo=github&color=%2329903b\"></a>\n",
    "\n",
    "This tool allows you to check if phone numbers are connected to Telegram accounts. \n",
    "Retrieving username, name, and IDs where available.\n",
    "\n",
    "To run it, you need:\n",
    "\n",
    "1. A Telegram account with an active phone number;\n",
    "2. Telegram `API_ID` and `API_HASH`, which you can get by creating a developers account at https://my.telegram.org/. \n",
    "\n",
    "This notebook will show you how to check if one or if a batch of phone numbers have Telegram accounts and show you their usernames.\n",
    "\n",
    "- Code and issue management: https://github.com/bellingcat/telegram-phone-number-checker\n",
    "- Python package: https://pypi.org/project/telegram-phone-number-checker/\n",
    "\n",
    " \n",
    "##### **Warning**: this notebook does not work on VsCode Notebook interpreter; it works at least on Google Colaboratory.\n",
    "This is due to the interactive nature of the tool which can only ask you for the Telegram sign-in code after it has started running, some notebook interpreters don't allow terminal calls to receive user input.\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Enter your Telegram API keys along your own phone number below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "API_ID = \"00000000\"\n",
    "API_HASH = \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n",
    "YOUR_PHONE = \"+11111111111\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you already have one or more target phone numbers to check you can replace the placeholder in the next cell. You can add just one or add multiple ones separated by a comma."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PHONE_NUMBERS_TO_CHECK = \"+99999999999,+00000000000\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1 - Install\n",
    "Let's install the library directly from its pypi package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install telegram-phone-number-checker"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# call the help menu to verify the installation\n",
    "!telegram-phone-number-checker --help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2 - checking phone numbers\n",
    "We will use the credentials from above and the target phone number(s).\n",
    "\n",
    "The first time you run this script you will need to receive a Telegram sign-in code in your account, and insert your account password (if you've set one). \n",
    "\n",
    "NOTE: On Google Colab the text box for your input may be hard to spot, click on the right side of the prompt text to see it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!telegram-phone-number-checker --api-id $API_ID --api-hash \"{API_HASH}\" --api-phone-number \"{YOUR_PHONE}\" --phone-numbers \"{PHONE_NUMBERS_TO_CHECK}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Your results should include each of the phone numbers along one of the following possible responses:\n",
    "\n",
    "1. If available, you will receive the Telegram Username, Name, and ID that are connected with this number.\n",
    "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.\n",
    "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.\n",
    "4. Or: another error occurred."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: A `YOUR_PHONE.session` file is created, don't share it as it creates your authentication tokens."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "open-source-research-notebooks-4sg58OrJ",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}