A Telegram bot for managing shared items (servers, devices, accounts, etc.) in teams. Built with Python and the python-telegram-bot library.
- SQLite database: Lightweight, file-based storage
- Auto-migration: Database schema updates automatically
- Permission system: Admin > Moderator > User hierarchy
- Conversation handlers: Multi-step command workflows
- Error handling: Comprehensive logging and user feedback
- Mobile-optimized: HTML formatting for better mobile display
- List Items: View all available items with status (✅ free, 📍 taken)
- Take Items: Reserve items with purpose tracking
- Free Items: Release items back to the pool
- Steal Items: Emergency takeover of items (with notifications)
- Filtering: Filter by group, type, or owner
- Item Management: Add, delete, and assign items
- Notification Management: Subscribe to item type notifications
- Inline Commands: Quick item creation with command arguments
- Type Management: Create and manage item types
- Moderator Management: Add/remove moderators
- Usage History: Track all item actions
- Database Management: Export, import, and reset database
- Batch Operations: Import multiple commands from files or text
- Type-specific notifications: Subscribe to specific item types
- Real-time alerts: Get notified when items are taken, freed, or stolen
- Group notifications: Notify entire teams about resource changes
- Python 3.8 or higher
- Poetry (for dependency management)
- A Telegram Bot Token (from @BotFather)
Create a new bot in Telegram:
- https://t.me/BotFather
/newbot- pick a name, say
companyprojectbot
Now you have a bot token, something long. You'll need it later.
-
Clone the repository
git clone <repository-url> cd item-bot
-
Install Poetry (if not already installed)
You can use your package manager or install it manually:
curl -sSL https://install.python-poetry.org | python3 --
Install dependencies
poetry install
-
Configure the bot
Copy the example configuration and edit it:
cp config.py.example config.py # Edit config.py with your bot token and admin user IDsImportant: The bot will not start without a valid
config.pyfile!To get your Telegram user ID, message @userinfobot on Telegram.
-
Run the bot
poetry run python bot.py
Or use the Poetry script:
poetry run bot
For development, you can use the bot watcher that automatically restarts the bot when files change:
poetry run bot-watcherSee /help full for all available commands.
The project uses Ruff for both linting and code formatting:
# Check linting and formatting
./lint.sh
# Auto-fix issues and format code
./format.sh
# Or run ruff commands directly:
poetry run ruff check . # Check for linting issues
poetry run ruff check --fix . # Auto-fix linting issues
poetry run ruff format . # Format codeBy default, the database is stored as resources.db in the current directory. You can change this in config.py:
DATABASE_PATH = "custom_path/resources.db"-
Bot doesn't respond
- Check if the bot token is correct
- Ensure the bot is started (@BotFather)
- Check console for error messages
-
Permission denied errors
- Verify your user ID is in ADMIN_USER_IDS
- Check if you're added as a moderator for mod commands
-
Database errors
- Ensure write permissions in the bot directory
- Check if the database file is corrupted (delete and restart)
-
Import/Export issues
- Ensure file encoding is UTF-8
- Check command format matches expected syntax
The bot logs important events to the console. For production, consider redirecting logs to a file:
poetry run bot 2>&1 | tee bot.logApache 2.0
Issues and pull requests are welcome.
Bot authors are not responsible for any damage caused by the bot or any GDPR or other personal data protection laws violations. You're on your own.