telegrify 1.0.5

Simple Telegram notification framework with plugin support

Telegrify

Simple, powerful Telegram notification framework with plugin support

Telegrify receives HTTP webhooks and forwards them as formatted Telegram messages. Perfect for alerts, order notifications, monitoring, CI/CD pipelines, and any system that needs to notify users via Telegram.

Features

• 🚀 Simple - Install, configure, run in under 5 minutes
• 🔌 Plugin System - Custom formatters without touching core code
• 📱 All Chat Types - Private chats, groups, supergroups, channels
• 📢 Broadcast - Send to multiple chats simultaneously
• 🖼️ Rich Media - Single images, photo galleries (up to 10)
• 🎹 Inline Keyboards - Interactive buttons with dynamic templates
• 🤖 Command Handlers - Respond to /start, /help, etc.
• 🌐 Environment Variables - Universal ${VAR} support in all config fields
• 🏷️ Custom Labels - Map order_id → 🆔 Order ID
• 🔀 Field Mapping - Map nested JSON fields with dot notation
• 📝 Jinja2 Templates - Conditionals, loops, filters
• 🎨 Formatters - Plain text, Markdown, or custom plugins
• 🔒 Secure - API key authentication
• 🌍 CORS Ready - Configurable CORS for web frontends
• ♻️ Reliable - Automatic retries with exponential backoff
• 🐳 Docker Ready - Easy containerized deployment

Quick Start

1. Install

pip install telegrify

2. Create Project

telegrify init my_notifier
cd my_notifier

3. Configure

Edit config.yaml:

bot:
  token: "${TELEGRAM_BOT_TOKEN}"

endpoints:
  - path: "/notify/orders"
    chat_id: "-1001234567890"
    formatter: "plain"

4. Run

export TELEGRAM_BOT_TOKEN="your-bot-token"
telegrify run

5. Send Notification

curl -X POST http://localhost:8000/notify/orders \
  -H "Content-Type: application/json" \
  -d '{"message": "New order received!", "order_id": 123}'

Documentation

• USAGE.md - Complete usage guide with examples
• CONTRIBUTING.md - Guide for contributors
• docs/PUBLISHING.md - Release and publishing guide
• docs/FUTURE.md - Roadmap and planned features

Configuration Reference

Bot Configuration

bot:
  token: "${TELEGRAM_BOT_TOKEN}"  # Bot token (supports env vars)
  test_mode: false                 # Log instead of sending (for testing)
  webhook_url: "${WEBHOOK_URL}"    # Public URL for receiving updates
  webhook_path: "/bot/webhook"     # Webhook endpoint path

Templates

templates:
  order_received: |
    🛒 *New Order \#{{ order_id }}*
    
    Customer: {{ customer }}
    Total: {{ total }}

Endpoint Configuration

endpoints:
  - path: "/webhook/orders"        # HTTP endpoint path
    chat_id: "8345389653"          # Single chat ID
    chat_ids:                      # Or multiple chat IDs
      - "8345389653"
      - "-1001234567890"
      - "@my_channel"
    formatter: "markdown"          # plain, markdown, or plugin name
    template: "order_received"     # Use template instead of formatter
    parse_mode: "MarkdownV2"       # Telegram parse mode
    labels:                        # Custom display labels
      order_id: "🆔 Order"
      customer: "👤 Customer"
    field_map:                     # Map incoming fields
      image_url: "product.photo"   # Supports dot notation
      image_urls: "product.gallery"

Server Configuration

server:
  host: "0.0.0.0"
  port: 8000
  api_key: "${API_KEY}"            # Optional authentication
  cors_origins: ["*"]              # CORS allowed origins

logging:
  level: "INFO"                    # DEBUG, INFO, WARNING, ERROR

Environment Variables

All config fields support ${VAR} syntax with optional defaults:

bot:
  token: "${TELEGRAM_BOT_TOKEN}"
  webhook_url: "${WEBHOOK_URL}"

server:
  port: "${PORT:-8000}"            # Use PORT or default to 8000
  cors_origins: ["${CORS_ORIGIN:-*}"]

Create .env file:

TELEGRAM_BOT_TOKEN=your_bot_token
WEBHOOK_URL=https://yourapp.onrender.com
PORT=3000

CLI Commands

telegrify init <name>     # Create new project
telegrify run             # Start server
telegrify run --reload    # Start with auto-reload (dev)
telegrify validate        # Validate config file
telegrify webhook setup   # Register webhook with Telegram
telegrify webhook info    # Show webhook status
telegrify webhook delete  # Remove webhook
telegrify --version       # Show version

Custom Plugins

Create plugins/my_formatter.py:

from telegrify import IPlugin

class MyFormatter(IPlugin):
    @property
    def name(self):
        return "my_formatter"
    
    def format(self, payload: dict, config: dict) -> str:
        prefix = config.get("prefix", "📢")
        return f"{prefix} {payload.get('message', '')}"

Use in config:

endpoints:
  - path: "/notify"
    chat_id: "123456789"
    formatter: "my_formatter"
    plugin_config:
      prefix: "🔔 Alert:"

API Response

Success:

{
  "status": "sent",
  "message_id": 123,
  "chat_id": "8345389653"
}

Error (structured JSON):

{
  "detail": {
    "error": "invalid_api_key",
    "message": "Invalid or missing API key"
  }
}

Error codes: invalid_api_key, formatter_not_found, send_failed

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/venopyx/telegrify.git
cd telegrify

# Run the setup script (creates venv, installs dependencies)
make install

# Or manually:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

Development Commands

# Activate virtual environment
source .venv/bin/activate

# Run tests
make test

# Run linters
make lint

# Format code
make format

# Build package
make build

# Clean build artifacts
make clean

Publishing

See docs/PUBLISHING.md for detailed release instructions.

Quick release:

make release version=1.0.4 notes=docs/RELEASE_NOTES.md

Getting Your Chat ID

1. Message @userinfobot on Telegram
2. Or send a message to your bot and check:

   curl https://api.telegram.org/bot<TOKEN>/getUpdates
   

License

MIT License - see LICENSE for details.