I Got Tired of Building Chat From Scratch in Django, So I Made a Package

#django #python #websocket #opensource

Every few months I'd end up in the same situation. New project, new client, same request: "can we add a chat feature?"

And every time, I'd spend days wiring up Django Channels, designing room models, figuring out how to track delivery, handle permissions, support multiple devices... all before writing a single line of actual product code.

So I finally built something to fix that.

The gap I kept running into

Django Channels is great but it's low level. It gives you WebSocket support and channel layers. What it doesn't give you is:

Room management (and different room types: one-to-one, group, and broadcast)
Message delivery and read receipts
Reactions, replies, and forwards
Object-level permissions for admins and moderators
Multi-device session support
Notification tracking for offline users

Every project I worked on needed all of these. Every project built them differently. None of them were quite right.

What I built

django-realtime-chat-messaging is a drop-in Django package that gives you a full WebSocket chat system with one endpoint, a clean event protocol, and enough flexibility to customize without rewriting everything.

Connecting from the frontend looks like this:

const ws = new WebSocket("ws://localhost:8000/messaging/?token=YOUR_TOKEN");

ws.send(JSON.stringify({
  event_type: "message.send",
  data: {
    room_id: "your-room-uuid",
    content: "Finally, chat that just works."
  }
}));

One connection. Everything flows through it.

What's included

Out of the box you get three room types (OneToOneChat, GroupChat, Channel) backed by a polymorphic Room table, full message lifecycle (create, reply, forward, edit, soft/hard delete), read receipts, delivery tracking, reactions, multi-device sessions, and object-level permissions via django-guardian.

There's also a notification scaffolding layer. The package tracks unread messages per user and dispatches them when the user connects. You plug in your own push provider. The package stays out of that.

The part I spent the most time on

Everything is swappable. Models, serializers, event handlers, permission handlers, even the consumer class and the WebSocket URL path are all configurable via settings.

REALTIME_CHAT_MESSAGING = {
    "CHAT_CONSUMER_CLASS": "myapp.consumers.CustomChatConsumer",
    "EVENT_HANDLER_CLASS": "myapp.handlers.CustomEventHandler",
    "WEBSOCKET_PATH": "chat/",
}

You can use it with zero config and have something working in under an hour, or you can swap out specific pieces as your needs grow. Nothing requires you to fork the package.

This is v0.1.0

First public release. The core is solid but I'm sure there are rough edges I haven't hit yet.

If you're a Django developer who has built chat before, I'd really value your take on the design decisions. If you're newer to WebSockets and want a real project to learn from, this might be a good one to dig into.