Django Telegram Bot

Build your Telegram bots in a Django way.

Decorator routing · Messages and keyboards in the admin · Fully typed

Documentation · Getting started · Examples · Migration guide

https://github.com/user-attachments/assets/5307e4c1-4f2a-4c2f-94e7-b05d9fec2788

Why dj_telegram_bot?

The fastest way to build a production-ready Telegram bot on Django. You write plain functions, decorate them with a trigger, and the library does the routing. Your texts and keyboards live in the database, so you can change them from the admin without a redeploy.

from dj_telegram_bot.core.guards import staff_required
from dj_telegram_bot.core.handlers import callback_handler, command_handler

@command_handler("start")
def start(ctx):
    ctx.bot.send_message(ctx.chat_id, "Hello!")

@callback_handler("buy_*")
def buy(ctx):
    item = ctx.callback_data.removeprefix("buy_")
    ctx.bot.answer_callback_query(ctx.callback_query.id, text=f"Added {item}")

@command_handler("stats")
@staff_required
def stats(ctx):
    ctx.bot.send_message(ctx.chat_id, "Staff only!")

Features

Install

pip install dj_telegram_bot

or with uv:

uv add dj_telegram_bot

Upgrading from 0.1.x? Read the Migration guide.

Quick start

1. Settings

# settings.py
INSTALLED_APPS = [..., "dj_telegram_bot.contrib"]

BOT_TOKEN = "your-telegram-bot-token"
TM_WEBHOOK_URL = "https://api.telegram.org"  # or your local Bot API server

2. URLs and migrations

# urls.py
urlpatterns = [..., path("telegram/", include("dj_telegram_bot.contrib.urls"))]

python manage.py migrate

3. Set the webhook (once)

curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=https://yourdomain.com/telegram/webhook/"

4. Write your first handler

# your_app/bot_handlers/start.py  (auto-discovered)
from dj_telegram_bot.core.handlers import command_handler

@command_handler("start")
def start(ctx):
    ctx.bot.send_message(ctx.chat_id, "Hello!")

Open your bot in Telegram and send /start. It answers Hello! 🎉

How it works

Telegram ──webhook──▶ Dispatcher ──▶ before handlers ──▶ Router ──▶ your function

Every update is wrapped in a handler object, passes through your @before_handler checks, and the router picks the first match: exact trigger, then the user's step, then wildcards.

Documentation

Full guide: https://zankoan.github.io/dj_telegram_bot/

Contributing

Contributions are welcome! Found a bug, have an idea, or spotted a typo in the docs? Open an issue or send a pull request.

Please keep pull requests small and focused

License

MIT