VFS Appointment Bot

Default / English — This file is the main project documentation.
العربية: التوثيق الكامل بالعربية

Automates checking (and related flows) on VFS Global appointment portals for selected destination countries, with optional GoLogin Profile Manager (GPM) integration, multi-window runs, and Telegram / Email / Twilio notifications.

Repository: github.com/code-root/vfs-appointment-bot

GitHub: CI & automation

• Workflow (Actions): .github/workflows/ci.yml — Python 3.10 / 3.12, pip install -r requirements.txt, compileall, and a small import smoke test (no Playwright browser download in CI).
• Dependabot (optional): .github/dependabot.yml for pip and GitHub Actions updates.

---

Disclaimer

Use this software only in line with VFS Global’s terms of service and applicable law. The authors are not responsible for misuse, account restrictions, or failed appointments. Credentials and automation are your responsibility.

Features

• Multi-country flows (destination): Germany (DE), Italy (IT), Portugal (PT), selected by factory routing in vfs_bot/vfs_bot_factory.py.
• Source country is an ISO 3166-1 alpha-2 code (e.g. AE); VFS login URLs are mapped in config/vfs-url.ini as SOURCE-DESTINATION keys.
• Playwright automation with playwright-stealth, realistic browser fingerprints, and configurable Chromium / Firefox / WebKit via config/browser.ini.
• Optional GPM: start/stop profiles over HTTP API (config/gpm.ini), optional Selenium helpers for GPM UI operations.
• Notifications: Telegram, Email, Twilio (wired through notification/notification_client_factory.py).
• Parallel windows: run_vfs_bot.py can run multiple threads (each driving its own browser session) until an appointment is found or you stop the process.
• Profile bookkeeping: optional GPM group VFS_Bot, used_profiles.json, helpers to populate/reset — see docs/PROFILE_MANAGEMENT_README.md.
• Proxy list support via utils/proxy_manager.py and proxies.txt (see .gitignore — do not commit secrets).

Requirements

• Python 3.8+ (3.10+ recommended for recent dependencies).
• Playwright browsers: at least Chromium; Firefox if browser.ini uses firefox.
• A valid VFS Global account and the correct portal URL for your source→destination pair.
• GPM (optional): default API base http://127.0.0.1:14517 (configurable).

Python dependencies (requirements.txt)

Package	Purpose
playwright	Browser automation
playwright-stealth	Stealth patches for Playwright
selenium	GPM UI / profile workflows where used
twilio	SMS / Twilio-backed notifications
tqdm	Progress display in batch scripts
requests	HTTP (GPM API, health checks)

Install:

pip install -r requirements.txt
playwright install chromium
# If using Firefox in config/browser.ini:
playwright install firefox

Quick start

1. Clone

   git clone https://github.com/code-root/vfs-appointment-bot.git
   cd vfs-appointment-bot

2. Configure config/ (all *.ini in config/ are merged — see utils/config_reader.py)

   • Copy GPM example if needed:

     cp config_gpm_example.ini config/gpm.ini

   • Create or edit config/vfs-credential.ini: VFS email and password (sensitive — listed in .gitignore).
   • Edit config/vfs-url.ini: add lines XX-YY = https://... where XX is source and YY is destination (e.g. AE-PT).
   • Edit config/notification.ini for Telegram / email / Twilio (sensitive — gitignored in template workflow).
   • Optional: config/appointment-params.ini defaults for visa_center, visa_category, visa_sub_category per country prefix (DE-, IT-, PT-).
   • Optional: config/browser.ini: type (chromium / firefox / webkit), headless, viewport-related options.
   • Optional: config/gpm.ini: enabled, api_url, profile_id, HTTP paths/methods, auto_stop, optional api_token, optional group_name for profile pools (see profile docs).

3. Run (recommended entry point)

   python run_vfs_bot.py

   On Windows you can use run.bat (UTF-8, dependency checks, then python run_vfs_bot.py). On Linux/macOS, run.sh runs python3 run_vfs_bot.py after basic checks.

4. Adjust behavior in run_vfs_bot.py

   At the top of main() you will find:

   • source_country_code, destination_country_code
   • appointment_params dict (or None)
   • max_iterations, number_of_windows (parallel threads)
   • Profile age window (20 minutes by default) before refreshing context
   • Inner check interval (5 seconds when continuous_check=True in vfs_bot.run)

Alternative CLI: main.py

main.py provides argparse flags:

• -sc / --source-country-code
• -dc / --destination-country-code
• -ap / --appointment-params as key=value,key2=value2

It runs a single bot instance in a loop with a countdown between iterations based on config/default.ini (interval).
Note: Run main.py from the repository root (same folder as run_vfs_bot.py). The file prepends the project root to sys.path so utils and vfs_bot import correctly.

Repository layout (detailed)

Entry points and scripts/ helpers

Run scripts/*.py from the repo root so config/ and relative paths resolve.

Path	Role
run_vfs_bot.py	Main runner: config validation, logging (UTF-8 on Windows), multi-threaded windows, calls get_vfs_bot() and vfs_bot.run().
main.py	Argparse-based CLI loop; logging to app.log + stdout.
scripts/create_gpm_profile.py	Interactive creation of one GPM profile via GpmSeleniumClient.
scripts/create_gpm_profiles.py	Batch creation (e.g. up to 100 profiles in group VFS_Bot) — see docs/PROFILE_MANAGEMENT_README.md.
scripts/populate_used_profiles.py	Marks existing profiles in the GPM group as used in used_profiles.json.
scripts/reset_used_profiles.py	Resets used-profile tracking.
scripts/test_gpm_connection.py	Probes GPM HTTP API (/api/v3/profiles, etc.) using config/gpm.ini.

Packages

Path	Role
vfs_bot/vfs_bot.py	Abstract VfsBot base: Playwright lifecycle, stealth, GPM integration hooks, login/appointment pipeline, notifications.
vfs_bot/vfs_bot_de.py	Germany-specific implementation.
vfs_bot/vfs_bot_it.py	Italy-specific implementation.
vfs_bot/vfs_bot_pt.py	Portugal-specific implementation.
vfs_bot/vfs_bot_factory.py	get_vfs_bot(source, destination) → UnsupportedCountryError if destination not DE/IT/PT.
notification/notification_client.py	Notification abstraction.
notification/telegram_client.py	Telegram bot API client.
notification/email_client.py	Email notifications.
notification/twilio_client.py	Twilio client.
notification/notification_client_factory.py	get_notification_client: channels telegram, email, and slack (in code, slack is wired to the Twilio client—use email or telegram unless you rely on that mapping).
utils/config_reader.py	Loads every config/*.ini plus optional VFS_BOT_CONFIG_PATH env override.
utils/config_writer.py	INI write helpers.
utils/timer.py	Countdown between checks (used by main.py).
utils/gpm_client.py	HTTP client for GPM profile start/stop and related API usage.
utils/gpm_selenium_client.py	Selenium-based GPM interactions (profile creation, etc.).
utils/profile_manager.py	Tracks used GPM profiles per group (used_profiles.json).
utils/proxy_manager.py	Proxy rotation / loading from proxies.txt.
utils/account_manager.py	Account-related helpers used by the bot flows.
utils/email_reader.py	Email reading utilities (e.g. OTP / mail workflows where implemented).
utils/date_utils.py	Date/time helpers.

config/ INI files

File	Section(s)	Purpose
vfs-credential.ini	vfs-credential	VFS login email/password (do not commit).
vfs-url.ini	vfs-url	SOURCE-DEST = full login URL mappings.
default.ini	default	interval (seconds) for main.py loop between attempts.
appointment-params.ini	appointment-params	Default DE-*, IT-*, PT-* visa center/category keys.
browser.ini	browser	Engine type, headless, optional UA/locale/timezone/viewport.
gpm.ini	gpm	GPM toggle, API URL, profile_id, HTTP paths, auto_stop, optional token, optional group_name.
notification.ini	(per implementation)	Telegram, email, Twilio settings (do not commit real secrets).

More documentation (docs/)

File	Content
docs/README_AR.md	Full documentation in Arabic.
docs/README_GPM.md	GPM setup, troubleshooting.
docs/README_RUN.md	Run commands (batch/shell vs direct python).
docs/PROFILE_MANAGEMENT_README.md	GPM group VFS_Bot, used_profiles.json, batch profiles.
docs/GITHUB.md	Creating the GitHub repo, push, auth, common errors.
docs/diagrams/PROCESS.md	Flowcharts (Mermaid): config → browser/GPM → VFS login → appointment → slots → notify.
docs/diagrams/vfs-journey-overview.svg	Illustrative SVG (same journey, Arabic + English labels).

Quick reference

Topic	Link
Run & install	docs/README_RUN.md
GPM	docs/README_GPM.md
GitHub push	docs/GITHUB.md
Process diagrams	docs/diagrams/PROCESS.md

Other tracked / generated artifacts

Item	Notes
app.log	Log file from runners; gitignored.
used_profiles.json	GPM profile usage tracker; gitignored.
proxies.txt	Proxy list; gitignored.
.env	Environment variables locally; treat as secret.
docs/images/error_email_field_not_found.png	Debug screenshot path (bot may overwrite).
assets/	Optional static assets (e.g. README QR images).

Supported countries (destination)

Code	Country
DE	Germany
IT	Italy
PT	Portugal

Extend by adding a new vfs_bot_*.py, registering it in vfs_bot_factory.py, and supplying URLs + appointment parameter handling as required by that VFS site.

Logging & troubleshooting

• Read app.log for stack traces and step logs.
• Verify config/vfs-url.ini key matches your source_country_code and destination_country_code (e.g. AE-PT).
• For GPM: run python scripts/test_gpm_connection.py and see docs/README_GPM.md.
• Windows: run.bat sets UTF-8 code page and PYTHONIOENCODING for Arabic/Unicode console output.

Contributing

1. Fork the repository
2. Branch: git checkout -b feature/your-feature
3. Commit and push
4. Open a Pull Request

License

Open source — see repository policy. Use responsibly.

Acknowledgements

• Playwright
• GoLogin / GPM (ecosystem)
• Contributors and issue reporters

---

Support this project

If this tool is useful to you, optional support helps maintain and improve it. Pick whatever works best for you.

Channel	How to support
PayPal	paypal.me/sofaapi
Binance Pay / UID	1138751298 — send from the Binance app (Pay / internal transfer when available).
Binance — deposit (web)	Deposit crypto (Binance) — sign in, pick the asset, then select BSC (BEP20).
BSC address (copy)	0x94c5005229784d9b7df4e7a7a0c3b25a08fd57bc

Network: Use BSC (BEP-20) only. This address is for USDT (BEP-20) and BTC on BSC (Binance-Peg / in-app “BTC” on BSC), matching the Binance deposit screens below. Do not send native Bitcoin (on-chain BTC), ERC-20, or NFTs to this address.

Deposit QR codes (scan in Binance or any BSC wallet)

USDT · BSC	BTC · BSC