Yaltopia Telegram Bot

A feature-rich Telegram bot for property listings built with TypeScript and organized using a feature-first architecture.

Features

• 📱 Phone-based Authentication: Users share phone number to login/register
• 🏠 Property Management: Browse, view, and add properties
• 👤 User Registration: Complete registration flow with validation
• 🔐 Secure Login: Password-based authentication for existing users
• 📋 Property Listings: View all available properties
• 🏘️ My Properties: Manage user's own property listings

Architecture

This project follows a feature-first approach for better scalability:

src/
├── shared/           # Shared utilities and services
│   ├── types/        # Common TypeScript interfaces
│   └── services/     # Shared services (API, Session)
├── features/         # Feature modules
│   ├── auth/         # Authentication feature
│   └── properties/   # Property management feature
└── bot/              # Bot orchestration

Setup

1. Install dependencies:

   npm install
   

2. Environment setup:

   cp .env.example .env
   

   Edit .env and add your Telegram bot token:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   API_BASE_URL=http://localhost:3000/api
   

3. Build the project:

   npm run build
   

4. Start the bot:

   npm start
   

   For development:

   npm run dev
   

Bot Flow

1. Authentication Flow

• User starts with /start
• Bot requests phone number
• If phone exists → Login with password
• If new user → Registration flow (name, email, password, confirm)

2. Main Menu (After Login)

• 🏘️ Browse Properties: View all available properties
• 🏠 My Properties: View user's own listings
• ➕ Add Property: Create new property listing
• 👤 Profile: View user profile information

3. Property Creation Flow

• Title → Description → Type (Rent/Sale) → Price → Area → Rooms → Toilets → Subcity → House Type

API Integration

The bot integrates with your existing backend APIs:

• POST /telegram-auth/telegram-register - User registration
• POST /telegram-auth/telegram-login - User login
• GET /telegram-auth/phone/{phone}/check - Check phone existence
• GET /telegram-auth/validate-email/{email} - Email validation
• GET /listings - Get all properties
• POST /listings - Create new property

Development

Scripts

• npm run build - Compile TypeScript
• npm run dev - Run in development mode with ts-node
• npm run watch - Watch mode for TypeScript compilation
• npm start - Run compiled JavaScript

Adding New Features

1. Create feature directory in src/features/
2. Add service class for API interactions
3. Add handler class for bot interactions
4. Integrate in main bot class (src/bot/bot.ts)

Getting Your Bot Token

1. Message @BotFather on Telegram
2. Use /newbot command
3. Follow the setup process
4. Copy the token to your .env file