Chat

1:1 & group messaging with realtime events

The chat block turns on a complete in-app messaging system: direct (1:1) and group conversations, message editing and deletion, typing indicators, read receipts with unread counts, and file attachments — all served over REST routes under basePath, with realtime events broadcast through the pubsub block.

Like everything in Nucleus, it pairs with a ready frontend: the ChatPanel component and useChat hook consume these routes and events directly, so a working messenger is a config key plus one component.

Configuration#

Defaults are production-sensible — enabling the block is usually enough. The knobs below tune group size, message limits and which social signals are broadcast.

config.nucleus.json — chat

1{2  "chat": {3    "enabled": true,4    "basePath": "/chat",5    "groupsEnabled": true,6    "maxGroupParticipants": 100,7    "maxMessageLength": 8000,8    "typingIndicators": true,9    "readReceipts": true,10    "attachments": { "enabled": true, "maxPerMessage": 5 }11  }12}

enabledbooleanOptional

Master switch. Routes register only when enabled and a database is configured.

Defaultfalse

basePathstringOptional

Mount point for the chat REST routes.

Default"/chat"

groupsEnabledbooleanOptional

Allow group conversations in addition to 1:1 direct chats. Groups require a title and get owner/admin/member roles.

Defaulttrue

maxGroupParticipantsnumberOptional

Cap on participants per group conversation.

Default256

maxMessageLengthnumberOptional

Maximum message length in characters, enforced on send and edit.

Default8000

editingEnabled / deletionEnabledbooleanOptional

Let senders edit or delete their own messages. Deletion is soft — content is cleared and deletedAt set, so the conversation history stays coherent.

Defaulttrue

typingIndicators / readReceiptsbooleanOptional

Broadcast typing and read events to other participants over the realtime channel. Read receipts also drive each participant's unreadCount.

Defaulttrue

realtimeTopicPrefixstringOptional

Topic prefix for the realtime events listed below.

Default"chat"

messagePageSizenumberOptional

Messages per history page. The messages endpoint cursor-paginates newest-first with limit clamped to 1–100.

Default50

attachments{ enabled?, maxPerMessage?, maxFileSizeBytes?, allowedMimeTypes? }Optional

File attachments on messages. Requires storage.enabled and storage.cdn.enabled; since enabled defaults to true, attachments switch on automatically once storage + CDN are configured. Size and MIME validation come from the storage block.

Endpoints#

All under basePath; every route reads the authenticated user from the request (401 without one). Conversation responses include participants, your participant record and your unreadCount.

GET /conversationslist

Your conversations, ordered by last activity. limit (default 30, max 100) + offset.

POST /conversationscreate

Direct ({ targetUserId }) or group ({ type: 'group', title, participantIds }). Direct pairs are deduplicated — re-creating an existing pair returns the existing conversation.

GET /conversations/:id/messageshistory

Newest-first cursor pagination: limit + before=<messageId> returns { messages, hasMore }.

POST /conversations/:id/messagessend

Send text and/or pre-uploaded attachment ids, optionally replying to another message (replyToId) with idempotency via clientMessageId. A multipart sibling — POST .../messages/upload — uploads files and sends in one call.

POST /conversations/:id/read · /typingsignals

Mark the conversation read (resets your unreadCount) and broadcast typing state.

PATCH · DELETE /messages/:idedit / delete

Edit or soft-delete your own messages — sender-only, enforced server-side.

POST · DELETE /conversations/:id/participantsmembership

Add or remove group participants. Only owner/admin can manage others; any member can leave.

From the frontend#

The frontend kit ships a complete messenger UI on top of these routes — conversation list, message thread, composer with attachments, typing and presence — themeable like every Nucleus component.

ChatPanelcomponent

The full messenger surface. Pairs with useChat / useChatStore and the NewConversationModal; styling via chatPanelTheme / extendChatPanelTheme.

usePubSubhook

The realtime hook the panel uses under the hood — subscribe to the chat topics yourself if you build a custom UI.

Related sections

Pub/Sub Storage Notification Frontend Components