django-realtime-chat-messaging
A reusable Django package that adds fully functional, production-ready real-time chat to any existing application. Connect a WebSocket, configure Django Channels, and you get private chats, group chats, broadcast channels, reactions, read receipts, delivery tracking, push notification scaffolding, and multi-device session support — without writing any chat business logic yourself.
Features
- Three room types — private one-to-one chats, group chats, and broadcast channels
- Full message lifecycle — create, reply, forward, edit, and delete (soft or hard)
- Reactions — one reaction per user per message, auto-replacing via signals
- Read receipts and delivery tracking — per message, per user, with bulk support
- Push notification scaffolding — integrates with Firebase, AWS SNS, or any provider
- Multi-device sessions — all active connections receive every message simultaneously
- Object-level permissions — via
django-guardian, automatically managed via signals - XSS-safe content — all message bodies sanitised with
bleach - Everything is swappable — models, serializers, handlers, permissions, consumer, and URL path
Installation
pip install django-realtime-chat-messaging
Quick Setup
settings.py
INSTALLED_APPS = [
"daphne",
"channels",
"django.contrib.admin",
"django.contrib.auth",
"polymorphic",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"guardian",
"realtime_chat_messaging",
]
ASGI_APPLICATION = "yourproject.asgi.application"
AUTHENTICATION_BACKENDS = (
"django.contrib.auth.backends.ModelBackend",
"guardian.backends.ObjectPermissionBackend",
)
CHANNEL_LAYERS = {
"default": {"BACKEND": "channels.layers.InMemoryChannelLayer"} # use Redis in production
}
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.locmem.LocMemCache",
"LOCATION": "chat-dev",
}
}
asgi.py
import os
import django
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "yourproject.settings")
django.setup()
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from realtime_chat_messaging.routing import websocket_urlpatterns
from django_channels_jwt_auth_middleware.auth import JWTAuthMiddlewareStack
application = ProtocolTypeRouter({
"http": get_asgi_application(),
"websocket": AllowedHostsOriginValidator(
JWTAuthMiddlewareStack(URLRouter(websocket_urlpatterns))
),
})
Migrate and run
python manage.py migrate
python manage.py runserver
Connect at ws://localhost:8000/messaging/ with a valid auth token.
Usage
All communication is over a single WebSocket connection using a structured event protocol.
// Create a one-to-one chat
ws.send(JSON.stringify({
event_type: "room.create",
data: { type: "OneToOneChat", participants: [2] }
}));
// Send a message
ws.send(JSON.stringify({
event_type: "message.send",
data: { room_id: "<room_uuid>", content: "Hello! 👋" }
}));
Requirements
- Python ≥ 3.11
- Django ≥ 4.2
- Redis (production)
Documentation
Full documentation at Read the Docs.
Includes:
- Quickstart guide
- Complete WebSocket event reference
- Custom models guide (with migration fix)
- Custom handlers, serializers, permissions, and consumer
- Deployment guide
License
Apache 2.0 — see LICENSE.
Metadata
Release files for django-realtime-chat-messaging 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_realtime_chat_messaging-0.1.0.tar.gz | 101.5 kB | Without provenance | Details for django_realtime_chat_messaging-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_realtime_chat_messaging-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for django_realtime_chat_messaging-0.1.0-py3-none-any.whl |
Total release size: 172.8 kB
Release files / django_realtime_chat_messaging-0.1.0.tar.gz
| Download URL | django_realtime_chat_messaging-0.1.0.tar.gz |
|---|---|
| Size | 101.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f0eb68c95502d8f5e66b6392a964f499d2aa2da4de6f46dc79826410c3a641e
|
|
BLAKE2b-256 checksum How to use checksums |
4c45298d1bdf5fedc519bf31ef1d60d2d73c6500680853ea623ae1ba2bd14572
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / django_realtime_chat_messaging-0.1.0-py3-none-any.whl
| Download URL | django_realtime_chat_messaging-0.1.0-py3-none-any.whl |
|---|---|
| Size | 71.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3be4a137c21f782eb3ceb6d6e80cd86d01ef19ec7d1fe735aa2a9cedb95a28e6
|
|
BLAKE2b-256 checksum How to use checksums |
898db2fa3e7f2c0687075143c8ccda5860177da143290174c7bd4a4babf3dbe1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for django-realtime-chat-messaging 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.