An intelligent, asynchronous Telegram bot that seamlessly aggregates individual photos, videos, animations, and documents into unified media albums.
Forwarding or sending dozens of photos and videos to Telegram chats individually creates spam and cluttered conversation histories. Album Maker Bot solves this by operating as an automated media aggregator.
Simply drop your photos, videos, GIFs, or document media into the bot chat. The bot queues them per user, listens for an inactivity cooldown or volume threshold, automatically formats them into standard Telegram Media Groups (up to 10 items per album), and dispatches them with rate-limit protection.
- ⚡ Automated Inactivity Cooldown: Starts a countdown timer (
AUTO_SEND_DELAY) upon receiving media. If no further items arrive, the album automatically sends. - 🎯 Threshold Trigger: Instantly dispatches an album once the queue reaches the configured limit (
AUTO_SEND_THRESHOLD, default & max: 10). - 🔄 Unlimited Queue & Auto-Chunking: Have 30 items? The bot slices queues exceeding 10 items into consecutive batches of 10, draining the queue without data loss.
- 🛡️ FloodWait & Rate-Limit Shielding: Sleeps 1.5 seconds between multi-batch chunks to prevent Telegram API FloodWait bans.
- 🔒 Per-User Concurrency Locks: Uses
asyncio.Lockper user to guarantee that concurrent uploads and timer triggers never interleave or corrupt batches. - 🧠 Smart Single-Item Fallback: If only a single photo or video is sent, the bot gracefully switches to
send_photo/send_videoto prevent Telegram API album errors. - 🏷️ First-Item Caption Preservation: The caption of your first uploaded item is seamlessly assigned as the album's primary caption.
- 📦 Broad Format Support:
- 🖼️ Photos (
JPEG,PNG,WEBP) - 🎥 Videos (
MP4,MKV,MOV) - 🎞️ Animations & GIFs
- 📄 Documents with
image/*andvideo/*MIME types
- 🖼️ Photos (
flowchart TD
A([User Sends Media]) --> B{Supported Type?}
B -- No --> C[Send Warning: Unsupported Document]
B -- Yes --> D[Add Item to User Queue]
D --> E{Queue Count >= Threshold?}
E -- Yes --> F[Trigger send_album_for_user]
E -- No --> G[Start / Reset Inactivity Timer]
G -->|Timer Expires| F
subgraph Dispatch [Queue Drainage Engine]
F --> H[Acquire Per-User asyncio.Lock]
H --> I{Items in Queue?}
I -- Single Item --> J[Send single Photo / Video]
I -- 2 to 10 Items --> K[Send Media Group Album]
I -- > 10 Items --> L[Slice First 10 Items -> Send Album]
L --> M[Wait 1.5s Flood Delay]
M --> I
J --> N[Release Lock & Clear Queue]
K --> N
end
| Command | Description |
|---|---|
/start |
Displays the bot introduction banner, configured parameters, and guide. |
/send_album |
Manually flushes and sends the current pending queue immediately. |
/status |
Returns the number of media items currently buffered in your queue. |
/cancel |
Clears your active media queue and aborts any active countdown timer. |
Settings are managed in config.py and can be overridden using environment variables:
| Variable | Type | Default | Description |
|---|---|---|---|
API_ID |
int |
123456 |
Your Telegram API ID from my.telegram.org. |
API_HASH |
str |
"your_api_hash" |
Your Telegram API Hash from my.telegram.org. |
BOT_TOKEN |
str |
None | Bot token generated by @BotFather. |
AUTO_SEND_THRESHOLD |
int |
10 |
Media count threshold before auto-sending (Telegram hard limit: 10). |
AUTO_SEND_DELAY |
float |
3.0 |
Seconds of inactivity before auto-dispatching the album. |
-
Clone the repository:
git clone https://github.com/prono69/Album-Maker-Bot.git cd Album-Maker-Bot -
Configure your credentials: Edit
config.pyor create a.envfile with your credentials:BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz API_ID=1234567 API_HASH=your_telegram_api_hash AUTO_SEND_THRESHOLD=10 AUTO_SEND_DELAY=3.0
-
Start the container:
docker compose up -d --build
-
Monitor logs:
docker compose logs -f
-
Clone & enter directory:
git clone https://github.com/prono69/Album-Maker-Bot.git cd Album-Maker-Bot -
Create and activate a virtual environment:
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies:
pip install -r requirements.txt
-
Set configuration: Set environment variables or update
config.py:export BOT_TOKEN="your_bot_token_here" export API_ID=123456 export API_HASH="your_api_hash"
-
Run the bot:
python album_bot_auto.py
To keep the bot running persistently in the background:
-
Create a service file:
sudo nano /etc/systemd/system/album-bot.service
-
Paste the following configuration:
[Unit] Description=Telegram Album Maker Bot After=network.target [Service] Type=simple User=root WorkingDirectory=/path/to/Album-Maker-Bot ExecStart=/path/to/Album-Maker-Bot/venv/bin/python album_bot_auto.py Restart=always RestartSec=5 Environment=BOT_TOKEN=your_token_here Environment=AUTO_SEND_THRESHOLD=10 Environment=AUTO_SEND_DELAY=3.0 [Install] WantedBy=multi-user.target
-
Enable and start:
sudo systemctl daemon-reload sudo systemctl enable album-bot sudo systemctl start album-bot
Album-Maker-Bot/
├── album_bot_auto.py # Main bot logic, event handlers & queue manager
├── config.py # Configuration loader, constants & logger setup
├── Dockerfile # Container build definition (Python 3.11-slim)
├── docker-compose.yml # Docker Compose service definition
├── requirements.txt # Project dependencies (kurigram, pytgcrypto)
├── .gitignore # Git ignore specification
└── README.md # Project documentation
Contributions, issues, and feature requests are welcome!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.