django-redis-aiogram

Run aiogram next to Django: write handlers as ordinary Django app code, and send Telegram messages from anywhere in the project.

One container runs the bot. Every other process — web, Celery, a management command — pushes the call onto a Redis list and returns, so a request never waits on Telegram.

  web, celery  ──bot.send()──▶  Redis list  ──▶  start_tgbot  ──▶  Telegram

Install

pip install django-redis-aiogram

# settings.py
import os

INSTALLED_APPS = [..., 'django_redis_aiogram']

TELEGRAM_BOT = {
    'TOKEN': os.environ.get('TELEGRAM_BOT_TOKEN', ''),
    'REDIS_URL': os.environ.get('REDIS_URL', ''),
}

Both may be empty. Nothing connects or validates credentials at import time, so tests and migrations run without them. Requires Python 3.10–3.14, Django 5.2+, aiogram 3.30+, redis 6.2+.

Use it

# myapp/tg_router.py — imported automatically from every installed app
from aiogram import F, types

from django_redis_aiogram import bot


@bot.message(F.text == '/start')
async def start(message: types.Message) -> None:
    await message.answer('hi')

# anywhere else in the project
from django_redis_aiogram import bot

bot.send(chat_id=CHAT_ID, text='Order approved')

python manage.py start_tgbot

A router module, a call, and one process running the bot. Everything else — rate limits, per-process opt-out, healthchecks — is configuration, and it is documented rather than required. Webhook mode is the one alternative that also asks for a URL route; Webhook has the four steps.

Documentation

The wiki is the documentation. Pages live in docs/wiki/, so they are reviewed in the same pull request as the code they describe and published from master.

Upgrading to 3.0: the deprecated telegram_bot package name is gone, so INSTALLED_APPS and imports have to name django_redis_aiogram. The upgrading page lists everything else that needs attention.

Contributing

CONTRIBUTING.md for the workflow, AGENTS.md for the same ground in the form coding agents read. Changes are in CHANGELOG.md; security reports go through SECURITY.md.