Skip to content

aiogram-sentinel

Rate limiting and debouncing middleware for aiogram v3 - Protect your Telegram bots from spam and abuse with powerful middleware and storage backends.

Updated: GitHub Pages deployment enabled with environment tracking

Quick Start

from aiogram import Bot, Dispatcher
from aiogram.types import Message
from aiogram_sentinel import Sentinel, SentinelConfig, rate_limit, debounce

# Create bot and dispatcher
bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

# Configure aiogram-sentinel
config = SentinelConfig(
    throttling_default_max=10,  # 10 messages per window
    throttling_default_per_seconds=60,  # 60 second window
    debounce_default_window=2,  # 2 second debounce
)

# Setup with one call - wires all middleware in recommended order
router, infra = await Sentinel.setup(dp, config)

# Your handlers with protection
@router.message()
@rate_limit(5, 60)  # 5 messages per minute
@debounce(1.0)      # 1 second debounce
async def handle_message(message: Message):
    await message.answer(f"Hello! Your message: {message.text}")

# Start your bot
await dp.start_polling(bot)

Features

  • Rate Limiting: Per-user/handler scopes with sliding window algorithm
  • Debouncing: Suppress duplicate messages/callbacks within a configurable window
  • Storage Backends: Memory (single worker) or Redis (multi-worker) with configurable prefixes
  • Decorators: @rate_limit and @debounce for easy handler configuration
  • Hooks: Optional on_rate_limited callback for custom user feedback
  • Setup Helper: Sentinel.setup(dp, cfg) wires middleware in recommended order
  • Typed, async-first, production-ready.

Installation

# Basic installation
pip install aiogram-sentinel

# With Redis support
pip install aiogram-sentinel[redis]

Documentation

🤝 Contributing

See CONTRIBUTING.md for development guidelines and setup instructions.

💬 Community & Support

  • 💬 Discussions - Questions, ideas, and community chat
  • 🐛 Issues - Bug reports and concrete feature requests

🎯 Where to Get Help

Need Help With Go To
Usage questions 💬 Q&A Discussions
Feature suggestions 💡 Ideas & Feature Requests
Bug reports 🐛 Issues
General chat 💬 General Discussion
Share projects 🎉 Show and tell
Project updates 📢 Announcements

Security

For security issues, see SECURITY.md.

License

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