django-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 — hands the call to a broker and returns, so a request never waits on Telegram. Four transports can carry it, and BROKER says which:

                              ┌─ Redis list ────┐
  web, celery ──bot.send()──▶ ├─ Redis Streams ─┤ ──▶ start_tgbot ──▶ Telegram
                              ├─ RabbitMQ ──────┤
                              └─ Kafka ─────────┘

Your code does not change with the row: the same bot.send(), handlers, event log and manage.py start_tgbot. What differs is what becomes of a message whose worker was killed mid-send, and what recovery is — a command, a clock, or the broker's own doing. Delivery compares them; each transport has a page of its own below.

Install

pip install 'django-aiogram[redis]'                 # Redis list, the default, or Redis Streams
pip install 'django-aiogram[rabbitmq,redis]'        # RabbitMQ
pip install 'django-aiogram[kafka,redis]'           # Kafka

One extra per transport, so a deployment downloads only the queue driver it uses. redis is in the other two lines for the FSM store, not the queue: FSM_STORAGE defaults to aiogram's Redis store, so a bot keeping chat state needs that driver whichever transport carries its messages, and FSM_STORAGE: 'memory' is what drops it.

Nothing is inferred from what happens to be installed: BROKER names the transport, and a base pip install django-aiogram imports and runs manage.py but carries no message. manage.py check names every extra that is missing, with the pip install line; Installation has the exceptions.

# settings.py
import os

INSTALLED_APPS = [..., 'django_aiogram']

TELEGRAM_BOT_DEFAULTS = {
    'TOKEN': os.environ.get('TELEGRAM_BOT_TOKEN', ''),
    # unset, BROKER resolves to RedisListBroker; the table above has the other three,
    # and each transport reads its own settings on top of these two
    '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+ and aiogram 3.30+; each transport then pins its own driver and asks for its own server — Installation has both, per row.

Use it

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

from django_aiogram import bot


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

# anywhere else in the project — `bots['support']` is the second bot, if there is one
from django_aiogram import bot, bots

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

python manage.py start_tgbot

More than one bot is a section each under TELEGRAM_BOTS, inheriting the defaults above and overriding what it names. One dispatcher and one handler tree serve all of them, bots configured alike share the connection and the consumer thread, and a queued message names the bot it is for wherever that bot has an identity — Multiple bots. Bots that arrive while it runs come from a provider, reconciled without a redeploy — Dynamic bots.

A router module, a call, and one process running the bot. That process gets Django's between-requests connection handling without having any requests — every update is bracketed with close_old_connections(), so a database that restarts under a long-running bot does not leave every handler raising InterfaceError until somebody notices. Nothing to configure; Deployment says what the healthcheck can and cannot see about it.

Everything else — rate limits, per-process opt-out, healthchecks — is configuration, documented rather than required. Webhook mode is the one alternative that also asks for a URL route: Webhook has the four steps.

Documentation

The documentation site 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 from 3.x: the distribution is django-aiogram and the import path is django_aiogram, the driver is an extra you now name, and the event log has a table of its own. The upgrading page walks it in order, migrate included.

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.