361 lines
12 KiB
Markdown
361 lines
12 KiB
Markdown
# 🏠 Yaltipia Telegram Bot
|
|
|
|
A powerful, production-ready Telegram bot for real estate property notifications. Users can create custom property alerts and receive instant notifications when matching properties become available.
|
|
|
|
[](https://nodejs.org/)
|
|
[](LICENSE)
|
|
[](SECURITY_DEPLOYMENT_CHECKLIST.md)
|
|
|
|
## 🚀 **Features**
|
|
|
|
### **🔔 Smart Notifications**
|
|
- **Custom Property Alerts** - Users set criteria (type, location, price range)
|
|
- **Automatic Matching** - Bot finds properties matching user preferences
|
|
- **Real-time Notifications** - Instant alerts via Telegram (with webhook support)
|
|
- **Flexible Filtering** - By property type, location, house type, and price
|
|
|
|
### **👤 User Management**
|
|
- **Secure Authentication** - Phone-based registration and login
|
|
- **Session Management** - Persistent user sessions with token-based auth
|
|
- **Notification Management** - Create, view, edit, and delete notifications
|
|
- **User-friendly Interface** - Intuitive inline keyboards and menus
|
|
|
|
### **📊 Admin Monitoring**
|
|
- **Real-time Health Monitoring** - System health checks every 30 minutes
|
|
- **Error Reporting** - Automatic error alerts to admin chat
|
|
- **Failed Login Tracking** - Security alerts for failed authentication attempts
|
|
- **Daily Reports** - Comprehensive system statistics
|
|
- **Performance Metrics** - Memory usage, uptime, and error rates
|
|
|
|
### **🔒 Security & Performance**
|
|
- **Rate Limiting** - Protection against spam and abuse
|
|
- **Input Validation** - Secure handling of user inputs
|
|
- **Error Handling** - Comprehensive error management
|
|
- **Security Headers** - Protection against common web attacks
|
|
- **Production Hardening** - Security best practices implemented
|
|
|
|
## 📋 **Quick Start**
|
|
|
|
### **Prerequisites**
|
|
- Node.js 16+ and npm
|
|
- Telegram Bot Token (from [@BotFather](https://t.me/botfather))
|
|
- Backend API for property data
|
|
- Admin Telegram chat for monitoring
|
|
|
|
### **Installation**
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <your-repository-url>
|
|
cd yaltipia-telegram-bot
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Create environment file
|
|
cp .env.example .env
|
|
|
|
# Configure your environment variables
|
|
nano .env
|
|
```
|
|
|
|
### **Configuration**
|
|
|
|
#### **🔍 Easy Chat ID Setup**
|
|
|
|
#### **🔍 Get Supergroup Chat ID & Topic ID**
|
|
|
|
For local development, create a simple script to get supergroup IDs:
|
|
|
|
```bash
|
|
# Run the script (create locally)
|
|
node quick-chat-info.js
|
|
```
|
|
|
|
**Simple script:** Add your bot to supergroup, send a message, get the IDs.
|
|
📖 **See [docs/GET_SUPERGROUP_IDS.md](docs/GET_SUPERGROUP_IDS.md) for the script code.**
|
|
|
|
#### **⚙️ Environment Variables**
|
|
|
|
Edit `.env` with your settings:
|
|
|
|
```env
|
|
# Bot Configuration
|
|
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
API_BASE_URL=https://your-api.com/api
|
|
WEBSITE_URL=https://yaltipia.com
|
|
|
|
# Notification System
|
|
NOTIFICATION_MODE=optimized
|
|
NOTIFICATION_CHECK_INTERVAL_HOURS=6
|
|
SEND_NO_MATCH_NOTIFICATIONS=false
|
|
|
|
# Admin Monitoring
|
|
ADMIN_CHAT_IDS=your_admin_chat_id
|
|
MONITORING_TOPIC_ID=your_topic_id
|
|
```
|
|
|
|
### **Start the Bot**
|
|
|
|
```bash
|
|
# Development
|
|
npm run dev
|
|
|
|
# Production
|
|
npm start
|
|
|
|
# With PM2 (recommended for production)
|
|
pm2 start src/bot.js --name "yaltipia-bot"
|
|
```
|
|
|
|
## 🏗️ **Architecture**
|
|
|
|
### **System Components**
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Telegram │ │ Yaltipia Bot │ │ Backend API │
|
|
│ Users │◄──►│ │◄──►│ (Property │
|
|
│ │ │ • Auth │ │ Data) │
|
|
└─────────────────┘ │ • Notifications│ └─────────────────┘
|
|
│ • Monitoring │ │
|
|
┌─────────────────┐ │ • Webhooks │ │
|
|
│ Admin Chat │◄───┤ │ │
|
|
│ (Monitoring) │ └──────────────────┘ │
|
|
└─────────────────┘ │ │
|
|
│ │
|
|
┌──────────────────┐ │
|
|
│ Webhook Server │◄─────────────┘
|
|
│ (Real-time) │
|
|
└──────────────────┘
|
|
```
|
|
|
|
### **Notification Modes**
|
|
|
|
| Mode | Description | Use Case |
|
|
|------|-------------|----------|
|
|
| **optimized** | Polls API every 6 hours | Current setup (no backend changes needed) |
|
|
| **full** | Real-time webhooks + polling backup | Future upgrade (requires backend integration) |
|
|
|
|
## 📖 **User Guide**
|
|
|
|
### **For End Users**
|
|
|
|
1. **Start the bot**: Send `/start` to the bot
|
|
2. **Register/Login**: Provide phone number and password
|
|
3. **Create notifications**: Use "🔔 Create Notification" button
|
|
4. **Set preferences**: Choose property type, location, price range
|
|
5. **Receive alerts**: Get notified when matching properties are found
|
|
|
|
### **Supported Property Criteria**
|
|
- **Property Type**: Rent, Sale
|
|
- **Location**: Any subcity (Bole, Kirkos, Addis Ketema, etc.)
|
|
- **House Type**: Apartment, Villa, Studio, Condominium, etc.
|
|
- **Price Range**: Minimum and maximum price limits
|
|
|
|
## 🛠️ **Development**
|
|
|
|
### **Project Structure**
|
|
|
|
```
|
|
yaltipia-telegram-bot/
|
|
├── src/
|
|
│ ├── bot.js # Main bot application
|
|
│ ├── api.js # Backend API client
|
|
│ ├── features/ # Bot features (auth, notifications, menu)
|
|
│ ├── services/ # Notification services
|
|
│ ├── utils/ # Utilities (monitoring, error handling)
|
|
│ └── webhook/ # Webhook handlers
|
|
├── scripts/ # Utility scripts
|
|
├── docs/ # Documentation
|
|
├── .env.example # Environment template
|
|
└── package.json # Dependencies and scripts
|
|
```
|
|
|
|
### **Available Scripts**
|
|
|
|
```bash
|
|
npm run dev # Start in development mode with nodemon
|
|
npm start # Start in production mode
|
|
npm test # Run tests (if available)
|
|
```
|
|
|
|
### **Environment Variables**
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `TELEGRAM_BOT_TOKEN` | Bot token from BotFather | Required |
|
|
| `API_BASE_URL` | Backend API endpoint | Required |
|
|
| `NOTIFICATION_MODE` | Notification system mode | `optimized` |
|
|
| `NOTIFICATION_CHECK_INTERVAL_HOURS` | Check frequency | `6` |
|
|
| `ADMIN_CHAT_IDS` | Admin chat IDs (comma-separated) | Required |
|
|
| `HEALTH_CHECK_INTERVAL_MINUTES` | Health check frequency | `30` |
|
|
|
|
## 🚀 **Deployment**
|
|
|
|
### **Quick Deployment**
|
|
|
|
For detailed deployment instructions, see [SECURITY_DEPLOYMENT_CHECKLIST.md](SECURITY_DEPLOYMENT_CHECKLIST.md)
|
|
|
|
```bash
|
|
# 1. Server setup
|
|
sudo npm install -g pm2
|
|
|
|
# 2. Clone and install
|
|
git clone <repo> && cd yaltipia-telegram-bot
|
|
npm ci --only=production
|
|
|
|
# 3. Configure environment
|
|
cp .env.production .env
|
|
# Edit .env with production values
|
|
|
|
# 4. Start application
|
|
pm2 start src/bot.js --name "yaltipia-bot"
|
|
pm2 save && pm2 startup
|
|
```
|
|
|
|
### **Docker Deployment**
|
|
|
|
```bash
|
|
# Build image
|
|
docker build -t yaltipia-bot .
|
|
|
|
# Run container
|
|
docker run -d \
|
|
--name yaltipia-bot \
|
|
--env-file .env.production \
|
|
-p 3001:3001 \
|
|
yaltipia-bot
|
|
```
|
|
|
|
### **Health Checks**
|
|
|
|
| Endpoint | Purpose |
|
|
|----------|---------|
|
|
| `GET /status` | Application health status |
|
|
| `GET /webhook/health` | Webhook service health |
|
|
|
|
## 📊 **Monitoring**
|
|
|
|
### **Built-in Monitoring Features**
|
|
|
|
- **System Health**: Memory usage, error rates, uptime tracking
|
|
- **User Activity**: Login attempts, notification creation, message processing
|
|
- **Error Tracking**: Automatic error reporting with stack traces
|
|
- **Performance Metrics**: Response times, API call success rates
|
|
|
|
### **Admin Notifications**
|
|
|
|
The bot automatically sends alerts to admin chat for:
|
|
- 🚨 **Critical system issues** (high error rates, memory problems)
|
|
- 🔐 **Security events** (failed login attempts, suspicious activity)
|
|
- 📊 **Daily reports** (system statistics and health summary)
|
|
- ⚠️ **Application errors** (with detailed error information)
|
|
|
|
## 🔗 **Webhook Integration**
|
|
|
|
### **Current Setup**
|
|
- **Mode**: Optimized polling (checks every 6 hours)
|
|
- **Backend Required**: No webhook integration needed
|
|
|
|
### **Future Enhancement**
|
|
- **Mode**: Real-time webhooks (instant notifications)
|
|
- **Backend Required**: Send HTTP POST to bot when properties are added/updated
|
|
|
|
For webhook integration guide, see [docs/WEBHOOK_INTEGRATION_GUIDE.md](docs/WEBHOOK_INTEGRATION_GUIDE.md)
|
|
|
|
## 🔒 **Security**
|
|
|
|
### **Security Features**
|
|
- ✅ **Rate limiting** (100 requests/minute per IP)
|
|
- ✅ **Input validation** and sanitization
|
|
- ✅ **Secure authentication** with token management
|
|
- ✅ **Error handling** without information leakage
|
|
- ✅ **Security headers** for webhook endpoints
|
|
- ✅ **Environment variable protection**
|
|
|
|
### **Security Best Practices**
|
|
- Never commit `.env` files to version control
|
|
- Use strong, unique bot tokens for production
|
|
- Regularly rotate authentication tokens
|
|
- Monitor admin chat for security alerts
|
|
- Keep dependencies updated
|
|
|
|
## 📚 **Documentation**
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [SECURITY_DEPLOYMENT_CHECKLIST.md](SECURITY_DEPLOYMENT_CHECKLIST.md) | Complete deployment guide for DevOps teams |
|
|
| [docs/WEBHOOK_INTEGRATION_GUIDE.md](docs/WEBHOOK_INTEGRATION_GUIDE.md) | Future webhook integration instructions |
|
|
| [docs/CONFIGURATION_GUIDE.md](docs/CONFIGURATION_GUIDE.md) | Detailed configuration options |
|
|
| [docs/MONITORING_SYSTEM.md](docs/MONITORING_SYSTEM.md) | Monitoring and alerting setup |
|
|
|
|
## 🤝 **Contributing**
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
### **Development Guidelines**
|
|
- Follow existing code style and patterns
|
|
- Add appropriate error handling
|
|
- Update documentation for new features
|
|
- Test thoroughly before submitting PR
|
|
|
|
## 📝 **License**
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🆘 **Support**
|
|
|
|
### **Getting Help**
|
|
- 📖 Check the [documentation](docs/) first
|
|
- 🐛 Report bugs via GitHub Issues
|
|
- 💬 Contact the development team
|
|
- 📧 Email: [your-support-email]
|
|
|
|
### **Common Issues**
|
|
- **Bot not responding**: Check bot token and network connectivity
|
|
- **API errors**: Verify API_BASE_URL and backend availability
|
|
- **No notifications**: Ensure users are logged in and have active notifications
|
|
- **Memory issues**: Monitor system resources and restart if needed
|
|
|
|
## 🎯 **Roadmap**
|
|
|
|
### **Current Version (v1.0)**
|
|
- ✅ Basic notification system with polling
|
|
- ✅ User authentication and management
|
|
- ✅ Admin monitoring and alerts
|
|
- ✅ Security hardening
|
|
|
|
### **Future Enhancements**
|
|
- 🔄 **Real-time webhooks** (when backend supports it)
|
|
- 📱 **Mobile app integration**
|
|
- 🔍 **Advanced search filters**
|
|
- 📊 **Analytics dashboard**
|
|
- 🌐 **Multi-language support**
|
|
|
|
---
|
|
|
|
## 🏆 **Production Ready**
|
|
|
|
This bot is **production-ready** with:
|
|
- ✅ **Comprehensive security** measures
|
|
- ✅ **Robust error handling** and monitoring
|
|
- ✅ **Scalable architecture** design
|
|
- ✅ **Complete documentation** for deployment
|
|
- ✅ **DevOps-friendly** configuration
|
|
|
|
**Deploy with confidence!** 🚀
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Built with ❤️ for Yaltipia**
|
|
|
|
[🏠 Website](https://yaltipia.com) • [📱 Telegram Bot](https://t.me/your_bot) • [📧 Support](mailto:support@yaltipia.com)
|
|
|
|
</div> |