🏷 Hashtag Bot

Telegram bot for generating unique hashtag batches with usage history tracking and authorization system.

📋 Features

Core Functionality

• 🔐 Authorization System - bot access via access code only
• 📁 Category Management - create, edit, delete categories with pagination
• 🏷 Hashtag Management - add, link and unlink hashtags
• 🔗 Flexible Linking - one hashtag can belong to multiple categories
• 🎲 Smart Generation - create batches of 10 hashtags with uniqueness control
• 📜 Batch History - view, copy and delete saved batches
• 💾 Persistent Database - all data saved between restarts

Advanced Features

• Pagination - convenient browsing of large lists (categories - 10/page, hashtags - 15/page)
• Interactive Editing - all actions via message editing (doesn't clutter chat)
• Uniqueness Control - hashtags don't repeat in the last 5 batches
• Link Existing Hashtags - link hashtags to categories without recreation
• Unlink Hashtags - remove hashtag from category with one tap

🎯 Generation Algorithm

1. User selects 1 to 9 categories
2. System collects all unique hashtags from selected categories
3. Filters hashtags, excluding those used in the last 5 batches
4. Randomly selects 9 unique hashtags
5. Adds fixed hashtag #fyp at the end
6. Prompts to save batch to history

Output format: #hashtag1 #hashtag2 #hashtag3 ... #fyp

🚀 Quick Start

Requirements

• Python 3.11+
• Docker and Docker Compose (for deployment)
• Telegram Bot Token from @BotFather

Local Installation

1. Clone the repository:

git clone https://github.com/topmonroe9/hashtag-bot.git
cd hashtag-bot

2. Create virtual environment:

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Create .env file:

cp .env.example .env

5. Configure environment variables (edit .env):

BOT_TOKEN=your_token_from_BotFather
ACCESS_CODE=your_access_code

6. Run the bot:

python main.py

🐳 Docker Deployment

On Local Machine

# Create .env file with token and access code
cp .env.example .env
nano .env

# Start the bot
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop
docker-compose down

On Remote Server (dev2.tech.apree)

1. Connect to server:

ssh dev2.tech.apree

2. Create directory for bot:

mkdir -p ~/hashtag-bot
cd ~/hashtag-bot

3. Copy project files (from local machine):

# Create archive
tar --exclude='venv' --exclude='__pycache__' --exclude='*.pyc' --exclude='*.db' --exclude='.git' -czf hashtag-bot.tar.gz .

# Copy to server
scp hashtag-bot.tar.gz dev2.tech.apree:~/hashtag-bot/

# On server, extract
cd ~/hashtag-bot
tar -xzf hashtag-bot.tar.gz
rm hashtag-bot.tar.gz

4. Create .env file (on server):

nano .env

BOT_TOKEN=your_token
ACCESS_CODE=your_code

5. Start the bot:

mkdir -p data
docker-compose up -d --build

6. Check status:

docker-compose ps
docker-compose logs -f

Managing Bot on Server

# View logs
docker-compose logs -f

# Restart
docker-compose restart

# Stop
docker-compose stop

# Start
docker-compose up -d

# Update code and restart
docker-compose down
docker-compose up -d --build

# Status
docker-compose ps

📖 Usage

First Launch

1. Find the bot on Telegram: @hashtags_apree_bot
2. Send /start
3. Authorize: /auth your_code

Main Commands

Command	Description
/start	Start bot and show main menu
/auth [code]	Authorization
/generate	Generate hashtag batch
/history	View saved batch history
/categories	Manage categories
/hashtags	Manage hashtags
/add_category	Quick add category
/add_hashtag	Quick add hashtag

Menu Buttons

• 🎲 Generate - directly opens batch generation
• 📜 History - shows last 10 saved batches
• 📁 Categories - opens all categories list
• 🏷 Hashtags - hashtag management menu

Example Workflow

1. Create a category:

   • Click "📁 Categories" → "➕ Add Category"
   • Enter name (e.g., "Lifestyle")

2. Add hashtags:

   • Click "🏷 Hashtags" → "➕ Add Hashtag"
   • Enter hashtag (e.g., "travel" or "#travel")
   • Select category to link

3. Link existing hashtags:

   • Open category
   • Click "➕ Link Hashtag"
   • Select hashtags from list

4. Unlink hashtag:

   • Open category
   • Click 🗑 next to hashtag

5. Generate batch:

   • Click "🎲 Generate"
   • Select 1 to 9 categories
   • Click "🎲 Generate"
   • Decide whether to save batch to history

6. Work with history:

   • Click "📜 History"
   • Use 📋 to copy batch
   • Use 🗑 to delete batch

🗂 Project Structure

hashtag-bot/
├── bot/
│   ├── database/
│   │   ├── __init__.py
│   │   └── database.py         # SQLite database operations
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── common.py           # /start, /auth, menu buttons
│   │   ├── categories.py       # Category management + pagination
│   │   ├── hashtags.py         # Hashtag management
│   │   ├── generate.py         # Batch generation
│   │   └── history.py          # Saved batch history
│   ├── middlewares/
│   │   ├── __init__.py
│   │   └── auth.py             # Authorization middleware
│   ├── utils/
│   │   ├── __init__.py
│   │   └── generator.py        # Hashtag generation logic
│   └── __init__.py
├── data/                       # Database (auto-created)
│   └── hashtag_bot.db
├── main.py                     # Entry point
├── config.py                   # Configuration
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker image
├── docker-compose.yml          # Docker Compose config
├── .dockerignore              # Docker ignore files
├── .env.example               # Environment variables example
├── .gitignore
└── README.md

💾 Database

SQLite database is automatically created at data/hashtag_bot.db.

Tables:

• users - Bot users with authorization flag
• categories - Hashtag categories
• hashtags - All hashtags
• category_hashtags - Category-hashtag links (many-to-many)
• history - Saved batch history (up to 10 per user)

🛠 Technologies

• aiogram 3.16.0 - Async framework for Telegram Bot API
• aiosqlite 0.20.0 - Async SQLite operations
• python-dotenv 1.0.1 - Environment variable management
• Docker & Docker Compose - Containerization

⚙️ Configuration

Environment Variables (.env)

Variable	Description	Default
BOT_TOKEN	Telegram bot token from @BotFather	Required
ACCESS_CODE	Access code for authorization	Required

Pagination Settings

In bot/handlers/categories.py:

CATEGORIES_PER_PAGE = 10  # Categories per page
HASHTAGS_PER_PAGE = 15    # Hashtags per page

Fixed Hashtag

In bot/utils/generator.py:

FIXED_HASHTAG = "#fyp"  # Always added at the end

🔒 Security

• ✅ .env file with token added to .gitignore
• ✅ Middleware checks authorization before each action
• ✅ Database protected from SQL injection (parameterized queries)
• ✅ Token and access code stored in environment variables

⚠️ Important:

• Never commit .env to git
• Use strong ACCESS_CODE for production
• Regularly backup data/hashtag_bot.db

🐛 Troubleshooting

Error: "BOT_TOKEN not found"

• Check .env file exists
• Ensure token is in format BOT_TOKEN=your_token

Bot doesn't respond

• Check main.py or Docker container is running
• Verify token is correct
• Check logs: docker-compose logs -f

"Access restricted" after /start

• Authorize: /auth your_code

Not enough hashtags for generation

• Add more hashtags to categories
• Use more categories for generation

Database not persisting (Docker)

• Check ./data directory exists
• Ensure volume is mounted: docker-compose ps
• Check permissions: ls -la ~/hashtag-bot/data/

📊 Monitoring

Viewing Logs

Locally:

# Logs output to console
python main.py

Docker:

# View logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Logs with timestamps
docker-compose logs -f -t

Database Inspection

# Enter container
docker exec -it hashtag-bot sh

# Access database
sqlite3 /app/data/hashtag_bot.db

# Queries
.tables
SELECT * FROM users;
SELECT * FROM categories;
.exit

🔄 Updates

Updating Code

1. On local machine:

git pull
docker-compose down
docker-compose up -d --build

2. On server:

# Copy new files
scp -r ./bot ./main.py ./requirements.txt dev2.tech.apree:~/hashtag-bot/

# On server
ssh dev2.tech.apree
cd ~/hashtag-bot
docker-compose down
docker-compose up -d --build

Database Migration

Database supports automatic migrations when adding new fields.

🤝 Support

If you encounter issues:

1. Check logs: docker-compose logs -f
2. Ensure all environment variables are configured
3. Create an Issue in the repository

📝 License

MIT

👨‍💻 Author

Created with ❤️ using Claude Code

---

Bot: @hashtags_apree_bot