API Reference¶

This page documents the public interfaces of every major component. Use this as a reference when subclassing or extending the package.

EventHandler¶

realtime_chat_messaging.utils.handlers.EventHandler

The aggregate handler combining all domain mixins. Each operation exists as an async/sync pair. Override the async method for extensions, side effects, and async integrations. Override the sync helper only when you need to replace or heavily modify the core DB logic. See Custom Handlers for full guidance.

Message methods

Async method (extend here)	Sync helper (replace here)	Returns
`create_message(data, user)`	`_create_message(data, user)`	`dict`
`react_to_message(data, user)`	`_react_to_message(data, user)`	`dict`
`message_acknowledged(user, message_id)`	`_message_acknowledged(user, message_id)`	`dict`
`modify_message(data)`	`_modify_message(data)`	`dict`
`create_read_receipt(user, message_id)`	`_create_read_receipt(user, message_id)`	`tuple`
`retreive_messages(room, data)`	`_retreive_messages(room, data)`	`dict`

Room methods

Async method (extend here)	Sync helper (replace here)	Returns
`create_room(user, data)`	`_create_room(user, data)`	`dict`
`list_rooms(user)`	`_list_rooms(user)`	`list`
`retreive_room(room)`	`_retreive_room(room)`	`dict`
`add_members_to_room(user_ids, room)`	`_add_members_to_room(user_ids, room)`	`tuple`
`remove_members_from_room(user_ids, room, session_user)`	`_remove_members_from_room(user_ids, room, session_user)`	`tuple`
`leave_room(user, room)`	`_leave_room(user, room)`	`dict \| None`
`join_room(user, room_id)`	`_join_room(user, room_id)`	`dict`
`modify_room(data, room)`	`_modify_room(data, room)`	`dict`

Session methods

Async method (extend here)	Sync helper (replace here)	Returns
`register_session(user, channel_name)`	`_register_session(user, channel_name)`	`Session`
`get_active_sessions(user_id)`	`_get_active_sessions(user_id)`	`list[str]`
`get_expired_sessions(user_id)`	`_get_expired_sessions(user_id)`	`list[str]`
`update_session(session)`	`_update_session(session)`	`None`

Notification methods

Async method (extend here)	Sync helper (replace here)	Returns
`get_and_group_chat_notifications(user)`	`_get_and_group_chat_notifications(user)`	`dict`
`create_chat_notification(message, type, user)` (static)	called synchronously inside `_create_message`	`list \| None`
`update_chat_notification(message_id, user, many)` (static)	called synchronously inside `_message_acknowledged`	`QuerySet`

PermissionHandler¶

realtime_chat_messaging.permissions.handlers.PermissionHandler

All methods are async wrappers around synchronous _have_* helpers. All return (bool, Room) except have_message_permission which returns bool.

Async method	Returns
`have_room_permission(user, room_id)`	`(bool, Room)`
`have_message_permission(user, message_id)`	`bool`
`is_message_sender(user, message_id)`	`(bool, Room)`
`have_room_permissions_to_add_or_remove_members(user, room_id, perm_phrase)`	`(bool, Room)`
`have_send_message_permission(user, data)`	`(bool, Room)`
`have_admin_privileges(user, room_id, action)`	`(bool, Room)`

ExceptionHandler¶

realtime_chat_messaging.utils.decorators.ExceptionHandler

Method	Description
`exception_handler_decorator(func)` (classmethod)	Decorator wrapping async consumer methods. Catches all Django/DRF exceptions and sends structured error JSON.
`send_error(consumer, detail, func, exc, code=4003)`	Send a structured error payload to the client and log the traceback.

Exception → code mapping:

DRFValidationError → 4003
DjangoValidationError → 4003
IntegrityError → 4005
ObjectDoesNotExist → 4004
Http404 → 4004
PermissionDenied → 4002
Exception (all others) → 4006

ChatMessagingConsumer¶

realtime_chat_messaging.consumers.ChatMessagingConsumer

See Custom Consumer for full usage guidance, all handler method names, and event mapper examples.

Lifecycle methods — always call super() when overriding:

connect() — authenticate, register session, restore group memberships, dispatch pending notifications
disconnect(close_code) — clean up expired sessions and remove from groups
receive(text_data, bytes_data) — parse JSON, look up event_type in the event map, call handler

Group and channel helpers:

send_group(group, event_type, data) — broadcast to a channel layer group
add_channel_to_group(group, user_id=None) — add all active sessions for a user to a group
discard_channel_from_group(group, user_id=None) — remove all active sessions for a user from a group
channel_setup() — fetch user_groups from cache and wire current channel name into each group
channel_cleanup() — remove expired session channel names from all groups

Consumer attributes (available after connect()):

self.user — authenticated Django user
self.session — current Session instance
self.channel_name — unique channel name for this connection; changes on every reconnect
self.channel_layer — configured channel layer instance
self.permission_handler — instance of the configured PermissionHandler class

Event mapper:

realtime_chat_messaging.variables.consumers.map_event_type_to_handlers

The default function that builds the event_type to handler method routing table used by receive(). Pass a custom mapper via EVENT_MAPPER in settings to add, restrict, or replace events. See Custom Consumer for the full default mapping table and customization examples.

Loader Utilities¶

realtime_chat_messaging.utils.loader

Functions for dynamically resolving configured models and serializers:

from realtime_chat_messaging.utils.loader import get_model, get_serializer

Message = get_model("Message")        # Returns configured Message class
Serializer = get_serializer("MessageSerializer")  # Returns configured class

get_model(name: str) → Model — look up a model by its settings key
get_serializer(name: str) → Serializer — look up a serializer by its settings key
import_and_verify_type_class(klass, repr, class_instance=None) — import and validate a class from a dotted path
import_and_verify_type_function(func, repr) — import and validate a function from a dotted path
clear_caches() — clear model and serializer caches (used in tests)

Settings¶

realtime_chat_messaging.conf.realtime_chat_settings

The global settings instance. Access any setting as an attribute:

from realtime_chat_messaging.conf import realtime_chat_settings

threshold = realtime_chat_settings.INACTIVITY_THRESHOLD
soft_delete = realtime_chat_settings.MESSAGE_SOFT_DELETE

See Settings Reference for all available settings and their defaults.

Cache Utilities¶

realtime_chat_messaging.utils.cache_utils

Async-safe functions for user group membership cache:

from realtime_chat_messaging.utils.cache_utils import (
    fetch_user_groups,
    update_user_groups,
    add_group_to_user_groups,
    remove_group_from_user_groups,
)

All functions are decorated with @sync_to_async and accept user_id as a string. Cache keys follow the format user:<user_id>:groups with no expiration. Values are JSON-serialised lists of group name strings.

WebSocket Close Codes¶

See Error Codes for the full table. Summary:

4001 — unauthenticated (connection closed)
4002 — permission denied
4003 — validation error
4004 — resource not found
4005 — integrity/constraint error
4006 — internal server error