stapel-chat

Conversations and messaging over WebSocket: direct (1:1, idempotent by participant pair), group and support threads on one model; realtime send/edit/delete with a monotonic per-conversation seq for order and a separate revision sequence for resume, so an edit or a deletion made while a client was offline reaches it on reconnect; deletion is a tombstone the id keeps arriving under, so client caches and offline databases learn what to purge; attachments carry the render metadata a bubble needs on first paint (aspect, byte size, a 16px base64 thumbnail, voice duration and waveform, document mime and extension) behind an OPEN type registry; typing and activity states, read and delivery receipts as ephemeral signals; a live inbox stream so the conversation list does not poll either; anchor-paginated history and lists; leaving a thread, which hides it for the person who left and takes nothing away from anybody else (their messages, the other party's copy and their own history by id all stay), un-hides on the next message written there, and is undoable (the left threads are listed by ?left=true and put back by POST /conversations/{id}/rejoin, which clears the departure and nothing else); and a support layer (queue, first-come assignment, open/pending/resolved with reopen).

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-chat

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

One model backs three kinds of thread: direct (1:1, idempotent by participant pair), group, and support (a customer↔operator thread with a queue and assignment lifecycle).

Realtime is the module, not a mode of it. Messages are sent and received over a WebSocket; REST serves history, hydration and the support lifecycle. A deployment that cannot serve the socket fails manage.py check rather than degrading into a product that refreshes on a timer — because a polling fallback a product can end up in silently is exactly how "websockets are done" became a false claim once already.

Quick start

INSTALLED_APPS = [
    # ...
    "stapel_core.django.apps.CommonDjangoConfig",
    "stapel_core.django.users",
    "rest_framework",
    "stapel_realtime",
    "stapel_chat",
]

CHANNEL_LAYERS = {"default": {
    "BACKEND": "channels_redis.core.RedisChannelLayer",
    "CONFIG": {"hosts": [REDIS_URL]},
}}
STAPEL_COMM = {"SIGNAL_TRANSPORT": "channels"}
STAPEL_REALTIME = {"ALLOWED_ORIGINS": ["https://app.example.com"]}  # with the port

# urls.py
urlpatterns = [path("chat/", include("stapel_chat.urls"))]

# asgi.py — the whole file
from django.core.asgi import get_asgi_application
from stapel_realtime.asgi import build_websocket_application

application = build_websocket_application(http_application=get_asgi_application())

pip install 'stapel-chat[realtime]'

What you get

• Two sockets. ws/chat/<conversation_id> is the resumable journal — hello{last_seq} → replay → live, with send / edit / delete / read / delivered / activity frames going through the same service layer the REST views call. ws/chat/inbox keeps the conversation list live, because a list with no socket refreshes on a timer forever however live the open thread is.
• Two sequences. seq is a message's immutable place in the thread — the sort key and the history anchor. rev_seq is its place in the revision journal, re-allocated on every edit and delete, and it is what realtime replay is anchored on: an edit made while a client was offline arrives in the catch-up. A client upserts by id, sorts by seq, and remembers rev_seq as its cursor.
• Edit and delete. An edit sets edited / edited_at. A delete leaves a tombstone: the id keeps being delivered with body: "", attachments: [] and deleted: true, so a client cache learns which id to purge. An id that stops arriving is an id nobody can purge. Retention is permanent.
• Attachments that render on first paint — aspect, byte size and a ~16px base64 thumbnail for images and GIFs; duration and a waveform image for audio; mime and extension for documents; poster and duration for video. The type set is an open registry — stickers are a settings line — and the metadata comes from stapel-cdn by comm, once, at send time.
• Receipts and activity. Separate delivery and read markers, both durable and both fanned out live; typing / recording_audio / sending_video / uploading_file as ephemeral signals with a TTL, from another open registry.
• Conversations — POST /chat/api/v1/conversations (direct / group / support); direct is get-or-create by participant pair. GET lists yours (anchor-paginated) with unread_count, and every row carries its own stream_key and socket_path. ?search= finds a thread by the three things its row draws — the counterpart's display name, the subject card's title and the last line — and ?unread=true narrows to the rows with a badge; both filter before the page is taken, so the anchor keeps its meaning.
• Leaving — DELETE /chat/api/v1/conversations/{id} is the caller leaving, not a delete: the thread drops off their list, counts and search, their live subscription is revoked and a chat.participant.left system line records it — while every message, every other participant and their own history by id stay exactly as they were. A new message from the other side brings the thread back. Staff erasure is not on this surface: user data has one deletion path, user.deleted.
• Messages — GET/POST /chat/api/v1/conversations/{id}/messages, PATCH/DELETE .../messages/{message_id}. History is anchored on seq, newest-first, both directions.
• Support — GET /chat/api/v1/support/queue, POST .../support/conversations/{id}/{assign,resolve,reopen}.

Configuration (STAPEL_CHAT)

There is no key that turns realtime off. See MODULE.md for the full wire contract, the extension seams and the anti-patterns.

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}