personal-telegram-bot ^v0.1.0

• 🎨 Beautiful UI — Modern interface with emojis and intuitive navigation
• 🏢 Company Profile — Display company name, description, and website
• ✏️ Write Message — Dedicated message writing interface
• 📩 Smart Forwarding — All user messages forwarded to administrator with user info
• 🛡️ Security — Built-in protection against XSS and malicious content
• 📊 Statistics — Admin commands for bot monitoring
• 📱 Cross-Platform — Runs on server, desktop, or mobile device (Termux)
• ⚡ Asynchronous — High performance using asyncio and aiogram
• 🔧 Easy Configuration — Simple JSON configuration file

1. Create a Bot via BotFather:

1. Open @BotFather in Telegram
2. Send /newbot command
3. Follow the instructions to set name and username
4. Save the bot token (looks like 1234567890:ABCdefGHIjklMNopQRstUVwxyz)

2. Get Your Chat ID:

1. Open @my_id_bot in Telegram
2. Send /start command
3. Save your numeric Chat ID

Prerequisites: Python 3.8+, pip, Git

# Clone repository
git clone https://github.com/smartlegionlab/personal-telegram-bot.git
cd personal-telegram-bot

# Create virtual environment
python -m venv venv

# Activate environment (Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

1. Environment Variables File (.env):

PERSONAL_API_TOKEN="your_bot_token_from_botfather"
ADMIN_CHAT_ID="your_numeric_chat_id"

2. Bot Configuration File (.config.json):

{
    "name": "Your Company Name",
    "description": "Detailed description of your company or personal services.",
    "url": "https://your-website.com"
}

# Activate virtual environment (if not already activated)
source venv/bin/activate

# Start the bot
python bot.py

Initial Termux Setup:

# Prevent device from sleeping
termux-wake-lock

# Update package manager
pkg update && pkg upgrade

# Install required packages
pkg install python python-pip git vim

# Install Rust (required for some dependencies)
pkg install rust

Bot Installation on Termux:

# Clone the repository
git clone https://github.com/smartlegionlab/personal-telegram-bot.git
cd personal-telegram-bot

# Create configuration files
touch .env .config.json

# Edit configuration files using vim
vim .env
# Add your token and chat ID, then save with :wq

vim .config.json
# Add your company info, then save with :wq

# Setup Python environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start the bot
python bot.py

> Your Telegram bot now runs directly on your Android phone! No server required.

For All Users:

• /start — Show welcome message with main menu

For Admin Only:

• /stats — View detailed bot statistics (messages processed, unique users, errors)
• /health — Check bot status and basic statistics

• Message Validation — Checks for malicious content and XSS attempts
• Length Limits — Messages limited to 4000 characters
• Content Filtering — Blocks scripts and dangerous patterns
• Input Sanitization — All user input is properly validated
• Secure Forwarding — Admin receives safe, formatted messages

1. User starts bot with /start command
2. Beautiful welcome screen appears with company info
3. User clicks "✏️ Write a Message" or types message directly
4. Message is validated for security and content
5. Admin receives formatted message with user details
6. User gets confirmation with thank you message
7. Conversation continues or user returns to main menu

Main Menu:

🌟 Welcome!

🏢 Name: Your Company Name
📝 About us: Your company description...

💬 We're here to help! Send us a message...

👇 Quick actions:
[✏️ Write a Message]
[🌐 Visit Website] [ℹ️ About]

Message Received by Admin:

📩 New Message Received

👤 User Information:
   • Name: John Doe
   • ID: 123456789
   • Username: @johndoe

💬 Message Content:
Hello, I'm interested in your services!

🔗 Go to chat

Common Issues:

1. Import errors with aiogram:

   pkg install rust
   pip install --upgrade pip
   pip install -r requirements.txt

2. Bot not starting: Check .env file exists and contains correct values, verify .config.json has valid JSON syntax
3. Messages not forwarding: Confirm ADMIN_CHAT_ID is correct, check bot has permission to message the admin
4. Termux issues: Ensure termux-wake-lock is active, check internet connection, verify sufficient storage space

Logs and Debugging: The bot provides detailed logs: INFO — Normal operations, WARNING — Security threats detected, ERROR — Operation failures.

Customizing Messages:

Edit the message templates in bot.py:

• _build_welcome_message() — Main menu
• _build_about_message() — About section
• _build_write_message_prompt() — Message writing prompt
• _send_thank_you() — Thank you message

Adding New Features:

The modular architecture makes it easy to extend:

• Add new middleware classes
• Register additional command handlers
• Extend configuration options
• Add new keyboard layouts

By using this software, you agree to the full disclaimer terms.

Software provided "AS IS" without warranty. You assume all risks.

Full legal disclaimer: See DISCLAIMER.md

License: BSD 3-Clause License