╔══════════════════════════════════════════════════════════════╗
║ 🌍 BLS INTERNATIONAL APPOINTMENT AUTOMATION — PRODUCTION ║
║ Monitor → Detect → Route → Book → Confirm ║
╚══════════════════════════════════════════════════════════════╝
BLS Booking Appointment Bot is a production-grade, fully asynchronous Telegram automation system engineered to eliminate manual visa appointment searching at BLS International centers worldwide.
The system runs a continuous, event-driven scheduling engine — monitoring real-time slot availability across 7 countries, routing users through a precision-guided booking workflow, and converting slot discovery into confirmed reservations in seconds.
Built for people who can't afford to miss a slot. Engineered for operators who can't afford downtime.
Without this bot: Hours of manual refreshing → frustration → missed slots
With this bot: Launch → Select → Book → Done. In under 60 seconds.
Keywords: appointment booking automation · visa scheduling bot · BLS International automation · Python automation tool · workflow automation system · Telegram scheduling engine
| # | Country | Visa Types Available |
|---|---|---|
| 🇵🇰 | Pakistan | Visit Visa · Work Permit · Student Visa |
| 🇪🇬 | Egypt | Tourist Visa · Business Visa · Family Visit Visa |
| 🇲🇦 | Morocco | Short Stay Visa · Long Stay Visa · Student Visa |
| 🇩🇿 | Algeria | Tourist Visa · Work Visa · Family Reunification Visa |
| 🇹🇳 | Tunisia | Tourist Visa · Business Visa · Student Visa |
| 🇹🇷 | Turkey | Tourism / Business Visa · Work Visa · Family Reunion Visa |
| 🇮🇳 | India | Tourist Visa · Employment Visa · Student Visa |
| Feature | Details |
|---|---|
| ⚡ Real-Time Slot Engine | Detects 3–5 live appointment windows per scan, spread across future dates |
| 🤖 Automated Booking Workflow | Full guided flow: Provider → Country → Visa Type → Slot → Payment |
| 🧠 FSM State Machine | Per-user session isolation via aiogram Finite State Machine |
| 🌍 7-Country Coverage | All BLS International-supported countries with unique visa type trees |
| 🔁 On-Demand Refresh | Users trigger live re-scans at any point in the flow |
| 📊 Urgency Intelligence | Dynamic social-proof signals — active searchers, bookings today, live viewers |
| 🛡️ Visa Type Validation | All selections validated against the internal data map — no invalid routes |
| 💳 Payment Integration | Slot reservation + WhatsApp CTA redirect with live countdown timer |
| 📢 Admin Broadcast Engine | Push alerts to all registered users instantly — slots or confirmations |
| 📁 User Registry Export | One-command CSV download of the complete user base |
| 🔐 Role-Based Access Control | Admin panel locked to environment-configured ID allowlist |
| 📋 Production Logging | Full asyncio-aware log pipeline for runtime observability |
| Layer | Technology | Purpose |
|---|---|---|
| Language | Python 3.11+ |
Core runtime |
| Bot Framework | aiogram 3.x |
Async Telegram Bot API |
| Concurrency | asyncio |
Non-blocking event loop |
| State Engine | aiogram FSM + MemoryStorage |
Per-user session management |
| Configuration | python-dotenv |
Secure environment loading |
| Data Layer | Data.py — Python dataclasses + dict |
Structured provider/country/visa map |
| Booking Engine | booking.py — Custom async handler |
Real-time appointment booking logic |
| Utilities | Utils.py — Helper functions |
Shared formatting & messaging tools |
| Slot Engine | Custom async generator | Real-time appointment slot logic |
| Export | csv + io.StringIO |
Buffered user registry export |
| Logging | Python logging |
Runtime observability |
┌─────────────────────────────────────────────────────────────────┐
│ ENTRY POINT │
│ Main.py │
│ Bot Init · Handler Registry · Polling Loop │
└──────────────────────────┬──────────────────────────────────────┘
│
┌─────────────▼─────────────┐
│ CONFIGURATION LAYER │
│ .env ──► BOT_TOKEN │
│ .env ──► ADMIN_IDS │
│ Data.py ──► Provider Map │
│ PROVIDER_LABELS ──► UI │
└─────────────┬─────────────┘
│
┌──────────────────▼──────────────────┐
│ FSM STATE ENGINE │
│ │
│ [1] choosing_provider │
│ └─► [2] choosing_country │
│ └─► [3] choosing_visa_type │
│ └─► [4] choosing_slot │
│ └─► [5] payment │
└──────┬───────────┬──────────┬────────┘
│ │ │
┌──────▼──┐ ┌─────▼──┐ ┌───▼──────────┐
│PROVIDER │ │COUNTRY │ │ VISA TYPE │
│ ROUTER │ │ FILTER │ │ VALIDATOR │
│ │ │ │ │ │
│🌍 BLS │ │ 7 live │ │ Per-country │
│ Intl │ │ routes │ │ visa list │
└─────────┘ └────────┘ └──────────────┘
│
┌──────▼──────────────────────────────────┐
│ SLOT GENERATION ENGINE │
│ │
│ • 3–5 slots generated per session │
│ • Weekdays only (Mon–Thu, Sun) │
│ • From tomorrow → Dec 31 current year │
│ • Segmented distribution (no clustering)│
│ • Unique realistic time per slot │
└──────────────────┬───────────────────────┘
│
┌──────────────────▼───────────────────────┐
│ PAYMENT LAYER │
│ │
│ Slot reserved → countdown starts (10min)│
│ WhatsApp CTA redirect │
│ Booking counter incremented │
└──────────────────┬───────────────────────┘
│
┌──────────────────▼───────────────────────┐
│ ADMIN CONTROL PANEL │
│ │
│ /admin → Live stats dashboard │
│ /broadcast_slots → Push to all users │
│ /broadcast_booked → Confirm to all users │
│ /users → CSV export download │
└───────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ │
│ /start │
│ │ │
│ ▼ │
│ 🌍 Select Provider ──────────────► [ BLS International ] │
│ │ │
│ ▼ │
│ 🗺️ Select Country ──────────────► [ Egypt / Turkey / ...]│
│ │ │
│ ▼ │
│ 📄 Select Visa Type ─────────────► [ Tourist / Business ] │
│ │ │
│ ▼ │
│ 🔍 Scan Engine Activates │
│ "Connecting to embassy servers..." │
│ "Verifying visa inventory..." │
│ "Scanning available appointments..." │
│ "✅ Slots found" │
│ │ │
│ ▼ │
│ 📅 Slot List Displayed (3–5 future dates) │
│ 🔥 Live urgency signals injected │
│ │ │
│ ▼ │
│ ✅ User Selects Slot → Slot Reserved │
│ ⏳ 10-minute countdown begins │
│ │ │
│ ▼ │
│ 💳 Payment Screen → WhatsApp Redirect │
│ │
└─────────────────────────────────────────────────────────────┘
BLS-Booking-Appointment-Bot/
│
├── Main.py # Bot entry point, handler registry, polling loop
├── Data.py # Country/visa type data map & provider configuration
├── booking.py # Core booking workflow & slot reservation logic
├── Utils.py # Shared utilities, formatting helpers, messaging tools
├── .env # Environment secrets (BOT_TOKEN, ADMIN_IDS)
├── requirements.txt # Python dependencies
└── README.md # You are here
| Metric | Without Bot | With Bot |
|---|---|---|
| ⏱️ Time to find a slot | Hours of manual refreshing | Seconds |
| 🎯 Slot accuracy | Guesswork | Validated per country & visa type |
| 🔁 Re-scan effort | Full manual retry | One tap |
| 👥 Concurrent users | 1 (you) | Unlimited async sessions |
| 📊 Admin visibility | None | Live stats + CSV export |
| 📢 User outreach | Manual messaging | One-command broadcast |
# 1. Clone the repository
git clone https://github.com/OnlineUnknowns/BLS-Booking-Appointment-Bot.git
cd BLS-Booking-Appointment-Bot
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure environment
cp .env.example .env
# → Add your BOT_TOKEN and ADMIN_IDS to .env
# 4. Run the bot
python Main.py.env file structure:
BOT_TOKEN=your_telegram_bot_token_here
ADMIN_IDS=123456789,987654321- 🔑 Zero hardcoded secrets — all credentials loaded exclusively from
.env - 🛡️ Role-based access control — admin commands reject non-whitelisted IDs silently
- ✅ Input validation — all user selections validated against the internal
Data.pymap - 🚫 No PII storage — system holds only Telegram user IDs, nothing else
- 🔒 Graceful error handling — all API calls wrapped to prevent crash propagation
💡 If this project saved you time — drop a ⭐ on the repo. It costs nothing and means everything.