README.md

<!--
Project: Telegram Bot
Author: Molla Samser
Designer & Tester: Rima Khatun
Website: https://rskworld.in
Contact: hello@rskworld.in | +91 93305 39277
Address: Nutanhat, Mongolkote, Purba Burdwan, West Bengal, India, 713147
Copyright: © 2026 RSK World. All rights reserved.
-->

# Telegram Bot - RSK World

**Category:** Custom Chatbots
**Difficulty:** Beginner
**Year:** 2026

## Overview
This project creates a robust Telegram bot with command handling, inline keyboards, and interactive features. It is designed to be a starting point for building complex Telegram automation tools.

## Features

### Core Features
- **Command Handling**: Easily parse and respond to user commands like `/start` and `/help`.
- **Inline Keyboards**: Interactive buttons and menus for enhanced user experience.
- **File Sharing**: Capabilities to handle file uploads and downloads.
- **Group Chat Support**: Functionality tailored for both private and group interactions.
- **Web Landing Page**: A beautiful, responsive landing page to showcase your bot.
- **Admin Dashboard**: PHP-based dashboard to monitor bot statistics and user data.

### Utility Features
- **QR Code Generator**: Generate QR codes from any text (`/qr`)
- **Text to Speech**: Convert text to voice notes (`/speak`)
- **PDF Creator**: Create PDF documents from text (`/pdf`)
- **Language Translator**: Translate text to multiple languages (`/translate`)
- **Weather Info**: Get weather information for any city (`/weather`)

### Advanced Features
- **AI Assistant**: Intelligent responses using OpenAI API or rule-based system (`/ai`)
- **Task Reminders**: Set personal reminders (`/remind`)
- **Password Generator**: Generate secure random passwords (`/password`)
- **URL Shortener**: Shorten long URLs (`/shorten`)
- **Calculator**: Perform mathematical calculations (`/calc`)
- **Unit Converter**: Convert between different units (`/convert`)
- **News Fetcher**: Get latest news articles (`/news`)
- **Text Summarizer**: Summarize long text (`/summarize`)
- **User Leaderboard**: View top users by XP (`/leaderboard`)
- **XP & Leveling System**: Users earn XP and level up by using the bot
- **User Profiles**: View detailed user statistics (`/profile`)

### Admin Features
- **Statistics Dashboard**: View comprehensive bot statistics (`/stats`)
- **Broadcast Messages**: Send messages to all users (`/broadcast`)
- **Database Export**: Export bot database (`/export`)
- **Web Dashboard**: Monitor users, feedback, and statistics via PHP dashboard

## Technologies Used
- **Telegram API** (python-telegram-bot library)
- **Python 3.8+** (Core bot logic)
- **SQLite** (Database for user data, feedback, reminders)
- **PHP** (Admin dashboard)
- **HTML5 & CSS3** (Landing page and dashboard UI)
- **JavaScript** (Frontend interactions)
- **OpenAI API** (Optional - for advanced AI features)
- **OpenWeatherMap API** (Optional - for real weather data)

## Getting Started

### Prerequisites
- Python 3.8+
- A Telegram Bot Token (Get one from [@BotFather](https://t.me/BotFather))

### Installation

1. **Clone or Download** the project.
2. **Install Dependencies**:
```bash
pip install -r requirements.txt
```
3. **Configuration**:
- Create a `.env` file in the project root (or copy from `.env.example` if available).
- Set the following variables:
```
TELEGRAM_BOT_TOKEN=your_bot_token_here
ADMIN_ID=your_telegram_user_id
```
- Optional: Add API keys for enhanced features:
```
OPENAI_API_KEY=your_openai_key (for AI features)
OPENWEATHER_API_KEY=your_weather_key (for real weather data)
```

### Running the Bot
```bash
python bot.py
```
The bot will start polling for updates. Logs will be saved to `bot.log`.

### Available Commands
- `/start` - Start the bot
- `/help` - Show all available commands
- `/features` - List all bot features
- `/profile` - View your profile and statistics
- `/leaderboard` - View top users
- `/qr <text>` - Generate QR code
- `/speak <text>` - Convert text to speech
- `/translate <lang> <text>` - Translate text
- `/pdf <text>` - Create PDF from text
- `/weather <city>` - Get weather info
- `/ai <question>` - Ask AI assistant
- `/remind <minutes> <message>` - Set reminder
- `/password [length]` - Generate password
- `/shorten <url>` - Shorten URL
- `/calc <expression>` - Calculator
- `/convert <value> <from> <to>` - Unit converter
- `/news [topic]` - Get news
- `/summarize <text>` - Summarize text
- `/feedback` - Send feedback
- `/stats` - Bot statistics (Admin only)
- `/broadcast <message>` - Broadcast message (Admin only)
- `/export` - Export database (Admin only)

### Web Dashboard
To view the admin dashboard:
1. Ensure PHP is installed and configured
2. Place the project in your web server directory
3. Access `dashboard.php` via your web browser
4. The dashboard shows user statistics, feedback, and leaderboard

### Web Landing Page
To view the project landing page, simply open `index.html` in your browser or serve it using a local server:
```bash
# Python simple server example
python -m http.server 8000
```
Then navigate to `http://localhost:8000`.

## Project Structure
```
telegram-bot/
├── bot.py # Main bot file
├── config.py # Configuration settings
├── handlers.py # Command handlers
├── database.py # Database operations
├── utils.py # Utility functions
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore file
├── dashboard.php # Admin dashboard
├── index.html # Landing page
├── project_info.php # Project metadata
└── assets/
├── css/
│ └── style.css
└── js/
└── script.js
```

## Recent Updates
- ✅ Enhanced error handling throughout the codebase
- ✅ Added comprehensive logging system
- ✅ Improved PDF generation with better Unicode support
- ✅ Added OpenAI integration for AI features
- ✅ Added OpenWeatherMap integration for real weather data
- ✅ Implemented user leaderboard and XP system
- ✅ Added multiple utility commands (password, URL shortener, calculator, etc.)
- ✅ Enhanced admin dashboard with more statistics
- ✅ Added file upload/download handling
- ✅ Improved database error handling
- ✅ Added .gitignore for better version control

## Contact & Credits
**Author:** Molla Samser
**Designer & Tester:** Rima Khatun
**Website:** [RSK World](https://rskworld.in)
**Contact:** [hello@rskworld.in](mailto:hello@rskworld.in)
**Address:** Nutanhat, Mongolkote, Purba Burdwan, West Bengal, India

© 2026 RSK World. All rights reserved.