<!-- README.md -->
<div align="center">
<img src="https://bitbytelab.github.io/assets/logos/bitbytelab.png" alt="BitByteLab Logo" height="120">
<h1 align="center">📞 WhatXtract</h1>
<p>
🕵️♂️ A powerful multithreaded CLI tool to <strong>extract and verify WhatsApp numbers</strong> using <strong>WhatsApp Web</strong> — no API needed.
</p>
<p>
WhatXtract is a <strong>robust</strong>, <strong>easy-to-use</strong> WhatsApp data extraction and automation toolkit built in Python. It lets you <strong>verify, extract, and validate contact numbers</strong> directly via WhatsApp Web with headless automation — powered by <code>selenium</code> and <code>undetected-chromedriver</code>.
</p>
<p>
Designed for <strong>developers</strong>, <strong>growth hackers</strong>, <strong>marketers</strong>, and <strong>data analysts</strong>, WhatXtract enables you to:
<ul align="left" style="text-align: left;">
<li>✅ Verify which numbers are active WhatsApp users</li>
<li>📤 Extract and clean up phone lists for lead gen or CRM sync</li>
<li>⚙️ Build custom WhatsApp workflows with automation at the core</li>
</ul>
</p>
<p>
<img src="https://img.shields.io/github/tag-version/bitbytelab/?style=flat-square" alt="GitHub Release Badge" />
<img src="https://img.shields.io/badge/license-MIT-red?style=flat-square" alt="License Badge" />
<img src="https://img.shields.io/pypi/pyversions/whatxtract?style=flat-square" alt="Python Version" />
<img src="https://img.shields.io/badge/status-Beta-orange?style=flat-square" alt="Project Status" />
<img src="https://img.shields.io/pypi/v/whatxtract?style=flat-square" alt="PyPI Version" />
<img src="https://img.shields.io/pypistats/monthly/whatxtract?style=flat-square" alt="PyPI Downloads" />
<img src="https://img.shields.io/github/languages/top/bitbytelab/whatxtract?style=flat-square" alt="Top Language" />
<a href="https://github.com/astral-sh/ruff">
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff Code Quality" />
</a>
</p>
</div>
---
## 🌟 Features
- ✅ **Detect Active/Inactive WhatsApp Numbers**
- 🧠 **Intelligent Login Handling** (QR scan and session reuse)
- 🔀 **Concurrent Multi-Account Checking**
- 🛡️ **Proxy Support** (optional, per account)
- 🗃️ **Persistent Profiles** – saves WhatsApp login sessions
- 🕶️ **Headless Mode** – optional
- 🕓 **Customizable Delays** – mimic human-like behavior
- 📂 **Custom Config Support** (`whatschecker.config.json`)
- 📈 **Built with Selenium + Undetected ChromeDriver**
- 💥 **Auto dependency installs on first run**
- 📇 **Extracts valid WhatsApp numbers from saved contacts on the device**
---
## 📦 How It Works
WhatXtract uses a multistep pipeline to extract valid WhatsApp users from your own contact list in a semi or fully-automated fashion:
1. **Prepare a `.txt` file** with phone numbers — one per line.
2. **WhatXtract converts this into a `.vcf` file** of ~5000 contacts per batch.
3. **Import the `.vcf` file to your WhatsApp installed Phone**.
4. **Launch WhatsApp and wait for sync.**
5. **Extracts relevant `stores` from WhatsApp IndexedDB**.
6. **Parses contacts** to extract name and number of valid users.
7. **Exports to a timestamped CSV file.**
> ℹ️ All the above steps can be performed automatically in sequence. <br>
> For now perform Step 3 and 4 manually.
---
## 🚀 Usage
### 1. 📦 Installation
```bash
git clone https://github.com/bitbytelab/WhatXtract.git
cd WhatXtract
chmod +x whatxtract.py
```
### 2. 🧪 First-time Setup (Scan QR)
```bash
./whatxtract.py --add-account
```
Scan the QR code to save your WhatsApp session. You can add multiple accounts this way.
---
### 3. 📤 Checking Numbers
Prepare an input file (e.g., `numbers.txt`) with **one number per line**:
```
+12025550123
+447911123456
+8801711123456
```
Run the checker:
```bash
./whatxtract.py --input numbers.txt --valid active.txt --invalid inactive.txt
```
You can also run in headless mode:
```bash
./whatxtract.py --input numbers.txt --valid active.txt --invalid inactive.txt --headless
```
---
### 4. 📇 Contacts Extraction
To extract valid WhatsApp numbers from your saved contacts:
```bash
python -m whatxtract --input contacts
```
This will:
1. Launch WhatsApp Web and log you in.
2. Extract contacts from WhatsApp database.
3. Save valid WhatsApp numbers along with name, about, and avatar info to a CSV.
The generated CSV will be saved as:
```
valid_whatsapp_contacts_YYYY_mm_dd_HH_MM.csv
```
📁 Example output preview:
| name | about | user_avatar |
|--------------|------------------------------|-------------------------------------------------|
| 019xxxxxxxxx | Always learning | https://media.whatsapp.net/... |
| 018xxxxxxxxx | Big brother watching you 😊 | default |
📝 **Note:** Contact names must be saved as numbers (i.e., "017xxxxxxx") to work properly with this feature.
### 5. 🧩 Optional Arguments
| Flag | Description |
|-----------------|--------------------------------------------------|
| `--input` | Input file with numbers |
| `--valid` | Output file for active numbers |
| `--invalid` | Output file for inactive numbers |
| `--delay` | Base delay in seconds between number checks |
| `--proxies` | List of proxies (e.g., `http://ip:port`) |
| `--headless` | Run Chrome in headless mode |
| `--add-account` | Launch new profile and scan QR to add account |
---
### 6. ⚙️ Config File Support
You can also define your settings in a `whatschecker.config.json` file:
```json
{
"input": "numbers.txt",
"valid": "active.txt",
"invalid": "inactive.txt",
"delay": 8,
"proxies": ["http://127.0.0.1:8000", null]
}
```
Then just run:
```bash
./whatxtract.py
```
---
## 🔐 Session Management
Saved WhatsApp sessions are stored in:
```bash
./WAProfiles/account1
./WAProfiles/account2
...
```
Remove a folder to reset that session.
---
## 🧰 Dependencies
- Python `3.9+`
- [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver)
- [selenium](https://pypi.org/project/selenium)
📦 Auto-installs on first run if not found!
---
## 📂 Folder Structure
<!-- START FOLDER STRUCTURE -->
<!-- END FOLDER STRUCTURE -->
---
## ❓ FAQ
**Q: Will my WhatsApp account get banned?**
A: This script mimics human behavior using real browser sessions and delays. Use proxies and multiple accounts to reduce risk. No API violations.
**Q: Is this open source?**
A: Yes! MIT licensed. Use it responsibly and contribute back.
---
Here’s a clean and friendly **Contribution** section you can add to your `README.md`:
---
## 🤝 Contribution
Contributions are welcome and appreciated!
* Feel free to **submit pull requests (PRs)** to improve features, fix bugs, or enhance documentation.
* Please ensure your code follows standard conventions and is well-tested where applicable.
* If you're planning a major change, consider opening an issue first to discuss it.
Let’s make this project better together! 💡
---
## ⚠️ Disclaimer
This tool is provided **for educational and research purposes only**.
* **Use at your own risk.**
* The author is **not responsible** for any misuse, damages, or consequences arising from the use of this tool.
* Automated or excessive interaction with WhatsApp services **may violate their Terms of Service** and **can lead to account bans or other penalties**.
* By using this tool, you agree that you understand the risks and take **full responsibility** for any outcomes.
> Always respect the platforms you interact with. This project is not affiliated with, endorsed by, or associated with WhatsApp or Meta in any way.
---
## 👨💻 Author
[Hasan Rasel](https://github.com/rsmahmud)
Made with ❤️ by [BitByteLab](https://github.com/bitbytelab)
📧 Contact: [bbytelab@gmail.com](mailto:bbytelab@gmail.com)
---
## 📄 License
MIT License – see [LICENSE](LICENSE) file for details.
---
## ⭐️ Star this project
If you find this useful, please consider starring the repo!
👉 [github.com/bitbytelab/WhatXtract](https://github.com/bitbytelab/WhatXtract)
Raw data
{
"_id": null,
"home_page": null,
"name": "whatxtract",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Contacts Extractor, WhatsApp, WhatsApp Automation, WhatsApp Extractor, WhatsApp Number Checker, WhatsApp User Checker, WhatsApp Validator, WhatsApp Web Scraper",
"author": null,
"author_email": "Hasan Rasel <rrss.mahmud@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/92/4b56e00924fcd954ab42d0b43a785030e15a51246160f28b3b02733a7844/whatxtract-1.0.8.tar.gz",
"platform": null,
"description": "<!-- README.md -->\n\n<div align=\"center\">\n \n <img src=\"https://bitbytelab.github.io/assets/logos/bitbytelab.png\" alt=\"BitByteLab Logo\" height=\"120\">\n <h1 align=\"center\">\ud83d\udcde WhatXtract</h1>\n\n <p>\n \ud83d\udd75\ufe0f\u200d\u2642\ufe0f A powerful multithreaded CLI tool to <strong>extract and verify WhatsApp numbers</strong> using <strong>WhatsApp Web</strong> \u2014 no API needed.\n </p>\n\n <p>\n WhatXtract is a <strong>robust</strong>, <strong>easy-to-use</strong> WhatsApp data extraction and automation toolkit built in Python. It lets you <strong>verify, extract, and validate contact numbers</strong> directly via WhatsApp Web with headless automation \u2014 powered by <code>selenium</code> and <code>undetected-chromedriver</code>.\n </p>\n\n <p>\n Designed for <strong>developers</strong>, <strong>growth hackers</strong>, <strong>marketers</strong>, and <strong>data analysts</strong>, WhatXtract enables you to:\n <ul align=\"left\" style=\"text-align: left;\">\n <li>\u2705 Verify which numbers are active WhatsApp users</li>\n <li>\ud83d\udce4 Extract and clean up phone lists for lead gen or CRM sync</li>\n <li>\u2699\ufe0f Build custom WhatsApp workflows with automation at the core</li>\n </ul>\n </p>\n\n <p>\n <img src=\"https://img.shields.io/github/tag-version/bitbytelab/?style=flat-square\" alt=\"GitHub Release Badge\" />\n <img src=\"https://img.shields.io/badge/license-MIT-red?style=flat-square\" alt=\"License Badge\" />\n <img src=\"https://img.shields.io/pypi/pyversions/whatxtract?style=flat-square\" alt=\"Python Version\" />\n <img src=\"https://img.shields.io/badge/status-Beta-orange?style=flat-square\" alt=\"Project Status\" />\n <img src=\"https://img.shields.io/pypi/v/whatxtract?style=flat-square\" alt=\"PyPI Version\" />\n <img src=\"https://img.shields.io/pypistats/monthly/whatxtract?style=flat-square\" alt=\"PyPI Downloads\" />\n <img src=\"https://img.shields.io/github/languages/top/bitbytelab/whatxtract?style=flat-square\" alt=\"Top Language\" />\n <a href=\"https://github.com/astral-sh/ruff\">\n <img src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff Code Quality\" />\n </a>\n </p>\n</div>\n\n---\n\n## \ud83c\udf1f Features\n\n- \u2705 **Detect Active/Inactive WhatsApp Numbers**\n- \ud83e\udde0 **Intelligent Login Handling** (QR scan and session reuse)\n- \ud83d\udd00 **Concurrent Multi-Account Checking**\n- \ud83d\udee1\ufe0f **Proxy Support** (optional, per account)\n- \ud83d\uddc3\ufe0f **Persistent Profiles** \u2013 saves WhatsApp login sessions\n- \ud83d\udd76\ufe0f **Headless Mode** \u2013 optional\n- \ud83d\udd53 **Customizable Delays** \u2013 mimic human-like behavior\n- \ud83d\udcc2 **Custom Config Support** (`whatschecker.config.json`)\n- \ud83d\udcc8 **Built with Selenium + Undetected ChromeDriver**\n- \ud83d\udca5 **Auto dependency installs on first run**\n- \ud83d\udcc7 **Extracts valid WhatsApp numbers from saved contacts on the device**\n\n---\n\n## \ud83d\udce6 How It Works\n\nWhatXtract uses a multistep pipeline to extract valid WhatsApp users from your own contact list in a semi or fully-automated fashion:\n\n1. **Prepare a `.txt` file** with phone numbers \u2014 one per line.\n2. **WhatXtract converts this into a `.vcf` file** of ~5000 contacts per batch.\n3. **Import the `.vcf` file to your WhatsApp installed Phone**.\n4. **Launch WhatsApp and wait for sync.**\n5. **Extracts relevant `stores` from WhatsApp IndexedDB**.\n6. **Parses contacts** to extract name and number of valid users.\n7. **Exports to a timestamped CSV file.**\n\n> \u2139\ufe0f All the above steps can be performed automatically in sequence. <br>\n> For now perform Step 3 and 4 manually.\n\n---\n\n## \ud83d\ude80 Usage\n\n### 1. \ud83d\udce6 Installation\n\n```bash\ngit clone https://github.com/bitbytelab/WhatXtract.git\ncd WhatXtract\nchmod +x whatxtract.py\n```\n\n### 2. \ud83e\uddea First-time Setup (Scan QR)\n\n```bash\n./whatxtract.py --add-account\n```\n\nScan the QR code to save your WhatsApp session. You can add multiple accounts this way.\n\n---\n\n### 3. \ud83d\udce4 Checking Numbers\n\nPrepare an input file (e.g., `numbers.txt`) with **one number per line**:\n\n```\n+12025550123\n+447911123456\n+8801711123456\n```\n\nRun the checker:\n\n```bash\n./whatxtract.py --input numbers.txt --valid active.txt --invalid inactive.txt\n```\n\nYou can also run in headless mode:\n\n```bash\n./whatxtract.py --input numbers.txt --valid active.txt --invalid inactive.txt --headless\n```\n\n---\n\n### 4. \ud83d\udcc7 Contacts Extraction\n\nTo extract valid WhatsApp numbers from your saved contacts:\n\n```bash\npython -m whatxtract --input contacts\n```\n\nThis will:\n\n1. Launch WhatsApp Web and log you in.\n2. Extract contacts from WhatsApp database. \n3. Save valid WhatsApp numbers along with name, about, and avatar info to a CSV.\n\nThe generated CSV will be saved as:\n\n```\nvalid_whatsapp_contacts_YYYY_mm_dd_HH_MM.csv\n```\n\n\ud83d\udcc1 Example output preview:\n\n| name | about | user_avatar |\n|--------------|------------------------------|-------------------------------------------------|\n| 019xxxxxxxxx | Always learning | https://media.whatsapp.net/... |\n| 018xxxxxxxxx | Big brother watching you \ud83d\ude0a | default |\n\n\ud83d\udcdd **Note:** Contact names must be saved as numbers (i.e., \"017xxxxxxx\") to work properly with this feature.\n\n\n\n### 5. \ud83e\udde9 Optional Arguments\n\n| Flag | Description |\n|-----------------|--------------------------------------------------|\n| `--input` | Input file with numbers |\n| `--valid` | Output file for active numbers |\n| `--invalid` | Output file for inactive numbers |\n| `--delay` | Base delay in seconds between number checks |\n| `--proxies` | List of proxies (e.g., `http://ip:port`) |\n| `--headless` | Run Chrome in headless mode |\n| `--add-account` | Launch new profile and scan QR to add account |\n\n---\n\n### 6. \u2699\ufe0f Config File Support\n\nYou can also define your settings in a `whatschecker.config.json` file:\n\n```json\n{\n \"input\": \"numbers.txt\",\n \"valid\": \"active.txt\",\n \"invalid\": \"inactive.txt\",\n \"delay\": 8,\n \"proxies\": [\"http://127.0.0.1:8000\", null]\n}\n```\n\nThen just run:\n\n```bash\n./whatxtract.py\n```\n\n---\n\n## \ud83d\udd10 Session Management\n\nSaved WhatsApp sessions are stored in:\n\n```bash\n./WAProfiles/account1\n./WAProfiles/account2\n...\n```\n\nRemove a folder to reset that session.\n\n---\n\n## \ud83e\uddf0 Dependencies\n\n- Python `3.9+`\n- [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver)\n- [selenium](https://pypi.org/project/selenium)\n\n\ud83d\udce6 Auto-installs on first run if not found!\n\n---\n\n## \ud83d\udcc2 Folder Structure\n\n<!-- START FOLDER STRUCTURE -->\n\n\n<!-- END FOLDER STRUCTURE -->\n\n---\n\n## \u2753 FAQ\n\n**Q: Will my WhatsApp account get banned?** \nA: This script mimics human behavior using real browser sessions and delays. Use proxies and multiple accounts to reduce risk. No API violations.\n\n**Q: Is this open source?** \nA: Yes! MIT licensed. Use it responsibly and contribute back.\n\n---\n\nHere\u2019s a clean and friendly **Contribution** section you can add to your `README.md`:\n\n---\n\n## \ud83e\udd1d Contribution\n\nContributions are welcome and appreciated!\n\n* Feel free to **submit pull requests (PRs)** to improve features, fix bugs, or enhance documentation.\n* Please ensure your code follows standard conventions and is well-tested where applicable.\n* If you're planning a major change, consider opening an issue first to discuss it.\n\nLet\u2019s make this project better together! \ud83d\udca1\n\n---\n\n## \u26a0\ufe0f Disclaimer\n\nThis tool is provided **for educational and research purposes only**.\n\n* **Use at your own risk.**\n* The author is **not responsible** for any misuse, damages, or consequences arising from the use of this tool.\n* Automated or excessive interaction with WhatsApp services **may violate their Terms of Service** and **can lead to account bans or other penalties**.\n* By using this tool, you agree that you understand the risks and take **full responsibility** for any outcomes.\n\n> Always respect the platforms you interact with. This project is not affiliated with, endorsed by, or associated with WhatsApp or Meta in any way.\n\n---\n\n## \ud83d\udc68\u200d\ud83d\udcbb Author\n[Hasan Rasel](https://github.com/rsmahmud) \nMade with \u2764\ufe0f by [BitByteLab](https://github.com/bitbytelab) \n\ud83d\udce7 Contact: [bbytelab@gmail.com](mailto:bbytelab@gmail.com)\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License \u2013 see [LICENSE](LICENSE) file for details.\n\n---\n\n## \u2b50\ufe0f Star this project\n\nIf you find this useful, please consider starring the repo! \n\ud83d\udc49 [github.com/bitbytelab/WhatXtract](https://github.com/bitbytelab/WhatXtract)\n",
"bugtrack_url": null,
"license": null,
"summary": "Extract and verify WhatsApp contact numbers via WhatsApp Web using an automation-powered Python toolkit.",
"version": "1.0.8",
"project_urls": {
"Homepage": "https://github.com/bitbytelab/whatxtract",
"Issues": "https://github.com/bitbytelab/whatxtract/issues"
},
"split_keywords": [
"contacts extractor",
" whatsapp",
" whatsapp automation",
" whatsapp extractor",
" whatsapp number checker",
" whatsapp user checker",
" whatsapp validator",
" whatsapp web scraper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "69b2580bc3dd8c759f2f260c6d2c2a827048d1afab09a5ff84c79a50c61daad7",
"md5": "fb834f835b84e3e18a97823447619662",
"sha256": "1de36e4dad7119f270372f0272ad4b80777721aa2ce84214318b1ec31f9eb188"
},
"downloads": -1,
"filename": "whatxtract-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb834f835b84e3e18a97823447619662",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30191,
"upload_time": "2025-07-23T21:36:17",
"upload_time_iso_8601": "2025-07-23T21:36:17.444401Z",
"url": "https://files.pythonhosted.org/packages/69/b2/580bc3dd8c759f2f260c6d2c2a827048d1afab09a5ff84c79a50c61daad7/whatxtract-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d924b56e00924fcd954ab42d0b43a785030e15a51246160f28b3b02733a7844",
"md5": "2ec21932491208263c7fd77f0bca5b7e",
"sha256": "c13cb76f95bb7c141907f49c4ebdfd5af225db4308573b42ea8c11c86bab7b7b"
},
"downloads": -1,
"filename": "whatxtract-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "2ec21932491208263c7fd77f0bca5b7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 533883,
"upload_time": "2025-07-23T21:36:24",
"upload_time_iso_8601": "2025-07-23T21:36:24.133743Z",
"url": "https://files.pythonhosted.org/packages/3d/92/4b56e00924fcd954ab42d0b43a785030e15a51246160f28b3b02733a7844/whatxtract-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 21:36:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bitbytelab",
"github_project": "whatxtract",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "whatxtract"
}
JSON
