A Python-powered queue-based notification system for Telegram
PyNotiQ is a lightweight and efficient Python application that reads messages from a queue and sends real-time notifications via Telegram. Built with the PyQueue client library, it supports both local and remote queue management. Perfect for alerting systems, deal tracking, and automated messaging.
- β Local & Remote Queue Support - Works with both local files and remote PyQueue servers
- β Telegram Integration - Sends notifications via Telegram Bot API
- β PyQueue Client - Built on the robust PyQueue client library
- β Flexible Configuration - Environment variables + command-line arguments
- β Exactly-once-ish Delivery - Delivered messages are deleted from the queue; failed ones are retried
- β Multiple Queue Types - Support for different queue configurations
- β Error Handling - Telegram timeouts, up to 5 delivery attempts per message
- β Easy Automation - Perfect for scheduled tasks and automation workflows
- Clone the repository:
git clone https://github.com/downlevel/pynotiq.git
cd pynotiq- Install required dependencies:
pip install -r requirements.txt- Set up your Telegram bot:
- Create a bot with @BotFather on Telegram
- Get your bot token
- Get your chat ID (you can use @userinfobot)
pynotiq/
βββ pynotiq.py # Main application script
βββ config.py # Configuration management
βββ test.py # Simple testing utility
βββ requirements.txt # Python dependencies
βββ .env # Environment variables (create this)
βββ queue.json # Local queue file (auto-created)
βββ README.md # This file
pynotiq.py- Main script that processes the queue and sends Telegram messagesconfig.py- Handles configuration from environment variablestest.py- Simple test script for adding messages to queue.env- Your configuration file (you need to create this)
Create a .env file in the project directory:
# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
# Queue Configuration
QUEUE_FILE_PATH=queue.json
PYQUEUE_QUEUE_TYPE=local
PYQUEUE_QUEUE_NAME=my-queue
PYQUEUE_SERVER_URL=http://localhost:8000
PYQUEUE_API_KEY=your_api_key_here- Local Queue: Uses local JSON file for message storage
- Remote Queue: Connects to a PyQueue server for distributed queue management
# Basic usage with local queue
python pynotiq.py -t your_bot_token -c your_chat_id
# Remote queue configuration
python pynotiq.py -qt remote -qs http://your-server:8000 -qn your-queue-name -qk your_api_key# Process queue with default configuration
python pynotiq.py# Local queue with custom file
python pynotiq.py -qt local -qf my_messages.json
# Remote queue
python pynotiq.py -qt remote -qs http://localhost:8000 -qn notifications
# Override Telegram credentials
python pynotiq.py -t YOUR_BOT_TOKEN -c YOUR_CHAT_ID
# Complete configuration
python pynotiq.py -qt remote -qs http://myserver:8000 -qn alerts -t BOT_TOKEN -c CHAT_ID-qt, --queue-type: Queue type (localorremote)-qs, --queue-server: Queue server URL (for remote queues)-qk, --queue-api-key: API key for PyQueue server-qn, --queue-name: Queue name-qf, --queue: Queue file path (for local queues)-t, --token: Telegram bot token-c, --chatid: Telegram chat ID-h, --help: Show help message
- requests - HTTP client for Telegram Bot API
- python-dotenv - Environment variable management
- pyqueue-client - Queue management client library
PyNotiQ uses the PyQueue client library for message management. Messages should follow this structure:
{
"id": "unique-message-id",
"timestamp": "2025-08-05T14:30:00.000000",
"message_body": {
"message_text": "π’ *Your notification message*\nπ° Price: β¬48.00\nπ [Link](https://example.com)",
"sent": false,
"message_type": "alert"
}
}id: Unique identifier for the message (UUID recommended)timestamp: ISO format timestamp when message was createdmessage_body.message_text: The actual message text (supports Telegram Markdown)message_body.sent: Legacy flag. Messages withsent: trueare treated as already delivered and removedmessage_body.message_type: Optional categorization (alert, deal, report, etc.)
- Initialize: PyNotiQ connects to the specified queue (local or remote) using PyQueue client
- Receive Messages: Reads batches of 10 with
queue.receive_messages(); received messages stay hidden from other consumers for 120 seconds (visibility timeout) - Send to Telegram: Sends each message with the Telegram Bot API (5s connect / 30s read timeout)
- Delete on Success: A delivered message is deleted with its receipt handle
- Retry on Failure: A failed message is left alone: it becomes visible again after the timeout and is retried by a later run. After 5 failed attempts it is dropped and logged
- Repeat: Keeps receiving until the queue is empty (at most 100 batches per run)
The queue therefore only holds messages still waiting to be delivered. Deduplication of repeated content is up to the producer (for example a cache of already-notified items).
PyNotiQ includes multiple test utilities to help you validate your setup:
# Add a single test message
python test.py
# Add multiple test messages
python test.py multiple# Add a single test message (using pyqueue-client)
python test_pyqueue_client.py
# Add custom message
python test_pyqueue_client.py add -m "Hello from PyNotiQ!"
# Add multiple test messages
python test_pyqueue_client.py bulk -n 5
# View current queue
python test_pyqueue_client.py view- Add test messages:
python test.py multiple - Process messages:
python pynotiq.py - Check your Telegram for received messages
{
"id": "alert_001",
"timestamp": "2025-08-09T10:30:00.000000",
"message_body": {
"message_text": "π¨ System Alert: Server CPU usage is above 90%",
"sent": false,
"message_type": "alert"
}
}{
"id": "deal_123",
"timestamp": "2025-08-09T14:15:30.000000",
"message_body": {
"message_text": "π’ *New Deal Found!*\nπ° *Price:* β¬25.00\nπ― *Target:* β¬50.00\nπ [View Item](https://example.com/item/123)",
"sent": false,
"message_type": "deal"
}
}{
"id": "report_001",
"timestamp": "2025-08-09T09:00:00.000000",
"message_body": {
"message_text": "π *Daily Report*\nβ’ Sales: β¬1,250\nβ’ Orders: 45\nβ’ New customers: 12\nβ’ System uptime: 99.9%",
"sent": false,
"message_type": "report"
}
}Run PyNotiQ every 5 minutes:
schtasks /create /tn "PyNotiQ" /tr "python C:\path\to\pynotiq.py" /sc minute /mo 5Add to crontab for every 5 minutes:
*/5 * * * * cd /path/to/pynotiq && python pynotiq.pyFROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "pynotiq.py"]- Connection Failures: Messages stay in the queue and are retried after the visibility timeout
- Invalid Messages: Skipped with error logging, other messages continue processing
- Missing Configuration: Falls back to environment variables and config defaults
- PyQueue Errors: Graceful handling of queue client connection issues
- Telegram API Errors: Failed messages are retried up to 5 times, then dropped with a log line
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
| Project | What it is |
|---|---|
| pyqueue-server | Self-hosted queue server with an AWS SQS-style REST API (FastAPI, SQLite or JSON) |
| pyqueue_client | Python client library (pip install pyqueue-client) for a local JSON queue or a remote server |
| pyqueue-ui | Web dashboard to browse queues and messages |
| pynotiq | Worker that delivers queue messages as Telegram notifications |
| keystorebot | Telegram bot that stores key-value pairs in a PyQueue queue |
This project is licensed under the MIT License - see the LICENSE file for details.