django-realtime-chat-messaging¶ Getting Started Introduction What It Does What It Does Not Do Design Philosophy Requirements Installation Requirements Dependencies Install the Package Configure INSTALLED_APPS Add Guardian Authentication Backend Configure the ASGI Application Configure Channel Layers Configure Cache Run Migrations Verify the Installation Quickstart Step 1 — Install Step 2 — Update settings.py Step 3 — Create asgi.py Step 4 — Run Migrations Step 5 — Add JWT Token Endpoint (optional but recommended) Step 6 — Connect and Chat What Happens Automatically Next Steps Getting Started The Single Endpoint The Event Protocol The Three Room Types What Happens Automatically Your First Conversation Key Behaviours to Know Next Steps Core Concepts Architecture High-Level Overview Request Lifecycle The Polymorphic Room Model The Settings System Async/Sync Boundary Rooms Room Types RoomProperty Permissions Summary Creating Rooms Messages Message Fields Sending Messages Content Sanitisation Media Attachments Editing and Deleting Messages Reactions Read Receipts Delivery Acknowledgement Retrieving Messages Typing Indicators Message Serializer Output Sessions How Sessions Work Session Model Fields Inactivity Threshold Heartbeat Multi-Device Support Cache Storage Notifications How Notifications Work Notification Types The chat.notifications Event Enabling and Disabling Integrating with a Push Service Overriding the On-Connect Dispatch Deleted Messages Permissions Permission Decorators Object-Level Permissions Managing Permissions via WebSocket Managing Admins and Moderators Customising Permissions The default_admin_names Parameter WebSocket API WebSocket Events Connection Payload Format Events and Dispatches — Full Reference Table On Connect Message Events Room Events Session Events Display Logic Tips Why Am I Not Receiving Broadcasts? Error Codes Error Payload Format Error Codes Handling Errors on the Client The Connection Close Code Invalid Event Types Custom Exception Handlers Configuration Settings Reference Behavioural Settings Pluggable Class Settings MODELS Dictionary SERIALIZERS Dictionary Complete Example Customization Custom Models Overview Step 1 — Create a New App Step 2 — Create Your Model Step 3 — Register in Settings Step 4 — Create a Custom Serializer Step 5 — Migrations and the Circular Dependency Fix Step 6 — Signals Available Abstract Models Extending Room Types Extending RoomProperty Swapping Multiple Models Custom Serializers The Serializer Mixin Pattern Available Mixins Customizing UserSerializer Customizing MessageSerializer Customizing Room Serializers Validation and extra_fields Custom Handlers Creating a Custom EventHandler Choosing Which Layer to Override Async Method Examples Sync Helper Examples Adding Sync DB Calls Inside an Async Override Customising the ExceptionHandler Available Methods to Override Custom Consumer Creating a Custom Consumer Available Methods to Override The Event Mapper Overriding connect and disconnect Adding New Event Handlers Adding Rate Limiting Using send_group in Custom Handlers Custom Permissions The Simplest Override Overriding the Sync Helper Layer Method Return Types The default_admin_names Parameter Deployment Deployment Redis ASGI Server Nginx Configuration systemd Service Production Settings Checklist Database Security Considerations Reference API Reference EventHandler PermissionHandler ExceptionHandler ChatMessagingConsumer Loader Utilities Settings Cache Utilities WebSocket Close Codes Troubleshooting Events Fire But No Broadcast Is Received WebSocket Connection Closes Immediately Changelog 0.1.0 (2026-02-08)