VtorynkaSaleBot

AI-powered Telegram bot for the Vtorynka real estate agency. It qualifies sellers, extracts property details from listing URLs, and guides them toward exclusive agency agreements.

---

Features

• AI-driven dialogue — qualification powered by gpt-4o-mini with sales-focused system prompts.
• Listing auto-parser — extracts price, rooms, area, and address from vtorynka.com.ua, OLX, and dom.ria.com URLs.
• Bilingual — full English / Ukrainian localization with per-user language switching.
• Lead capture — saves qualified seller leads (name + phone) and notifies a manager chat instantly.
• Async by default — aiomysql, aiohttp, and AsyncOpenAI keep the bot responsive under load.
• Persistent context — rolling 20-message conversation window stored in MySQL.

Tech Stack

Layer	Technology
Bot runtime	python-telegram-bot 21.0
AI	OpenAI — gpt-4o-mini
Database	MySQL via aiomysql connection pool
Scraping	aiohttp + regex/meta extraction
Container	Docker + docker-compose
Testing	pytest + pytest-asyncio + coverage

Quick Start

1. Clone & install

git clone <repo-url>
cd VtorynkaSaleBot

python -m venv .venv
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\activate           # Windows

pip install -r requirements.txt

2. Configure

Create a .env file in the project root:

TELEGRAM_BOT_TOKEN=your_bot_token
OPENAI_API_KEY=your_openai_key
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=
MYSQL_DATABASE=vtorynka_bot
MANAGER_CHAT_ID=your_chat_id

3. Run

python main.py

Docker

Spin up the bot together with MySQL in one command:

docker-compose up -d

Testing

pip install -r requirements-test.txt

# run all tests
pytest tests/ -v

# with coverage report
pytest tests/ --cov=. --cov-report=term-missing

Project Structure

.
├── main.py              # Entry point
├── bot.py               # Telegram handlers (/start, /reset, /language, messages)
├── agent.py             # OpenAI client, JSON parsing, response formatting
├── listing_parser.py    # Async scrapers for vtorynka / OLX / dom.ria
├── database.py          # MySQL pool, conversations & seller_leads tables
├── config.py            # System prompts and environment config
├── locales.py           # i18n templates (en / uk)
├── tests/               # Unit tests + fixtures
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

How It Works

User message
   └─▶ Parse URLs & extract listing data
        └─▶ Enrich system prompt
             └─▶ OpenAI API call
                  └─▶ Parse JSON { message, seller_lead }
                       ├─▶ Save conversation history
                       ├─▶ Persist seller lead (if name + phone present)
                       └─▶ Notify manager + reply to user

Bot Commands

Command	Purpose
/start	Begin a new conversation
/reset	Clear conversation history
/language	Switch between English and Ukrainian

Contributing

Run the test suite before opening a PR:

pytest tests/ -v

Preserve the async-first patterns — never introduce blocking calls inside bot handlers.