Skip to content
downlevelPublic

About

Telegram notifications from a message queue: a Python worker that reads PyQueue (local or remote) and delivers alerts.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

Β 

History

20 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

PyNotiQ

A Python-powered queue-based notification system for Telegram

Description

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.

✨ Features

  • βœ… 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

πŸš€ Installation

  1. Clone the repository:
git clone https://github.com/downlevel/pynotiq.git
cd pynotiq
  1. Install required dependencies:
pip install -r requirements.txt
  1. Set up your Telegram bot:

πŸ“ Project Structure

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

Key Files

  • pynotiq.py - Main script that processes the queue and sends Telegram messages
  • config.py - Handles configuration from environment variables
  • test.py - Simple test script for adding messages to queue
  • .env - Your configuration file (you need to create this)

βš™οΈ Configuration

Method 1: Environment Variables (Recommended)

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

Queue Types

  • Local Queue: Uses local JSON file for message storage
  • Remote Queue: Connects to a PyQueue server for distributed queue management

Method 2: Command Line Arguments

# 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

πŸ“– Usage

Basic Usage

# Process queue with default configuration
python pynotiq.py

Advanced Usage

# 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

Command Line Options

  • -qt, --queue-type: Queue type (local or remote)
  • -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

πŸ“¦ Dependencies

  • requests - HTTP client for Telegram Bot API
  • python-dotenv - Environment variable management
  • pyqueue-client - Queue management client library

πŸ“‹ Message Format

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"
    }
}

Message Properties

  • id: Unique identifier for the message (UUID recommended)
  • timestamp: ISO format timestamp when message was created
  • message_body.message_text: The actual message text (supports Telegram Markdown)
  • message_body.sent: Legacy flag. Messages with sent: true are treated as already delivered and removed
  • message_body.message_type: Optional categorization (alert, deal, report, etc.)

πŸ”„ How It Works

  1. Initialize: PyNotiQ connects to the specified queue (local or remote) using PyQueue client
  2. Receive Messages: Reads batches of 10 with queue.receive_messages(); received messages stay hidden from other consumers for 120 seconds (visibility timeout)
  3. Send to Telegram: Sends each message with the Telegram Bot API (5s connect / 30s read timeout)
  4. Delete on Success: A delivered message is deleted with its receipt handle
  5. 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
  6. 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).

πŸ§ͺ Testing

PyNotiQ includes multiple test utilities to help you validate your setup:

Quick Testing with test.py

# Add a single test message
python test.py

# Add multiple test messages
python test.py multiple

Advanced Testing with test_pyqueue_client.py

# 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

Complete Test Workflow

  1. Add test messages: python test.py multiple
  2. Process messages: python pynotiq.py
  3. Check your Telegram for received messages

πŸ“ Examples

Example 1: Basic Alert

{
    "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"
    }
}

Example 2: Deal Notification (with Markdown)

{
    "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"
    }
}

Example 3: Daily Report

{
    "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"
    }
}

πŸ”§ Automation

Windows Task Scheduler

Run PyNotiQ every 5 minutes:

schtasks /create /tn "PyNotiQ" /tr "python C:\path\to\pynotiq.py" /sc minute /mo 5

Linux Cron Job

Add to crontab for every 5 minutes:

*/5 * * * * cd /path/to/pynotiq && python pynotiq.py

Docker Integration

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "pynotiq.py"]

πŸ›‘οΈ Error Handling

  • 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

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

PyQueue ecosystem

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

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

About

Telegram notifications from a message queue: a Python worker that reads PyQueue (local or remote) and delivers alerts.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages