💬 Chat Blocks

Chat blocks provide comprehensive functionality for real-time communication in Nodeblocks applications. These blocks handle chat lifecycle operations including channels, messages, and subscriptions.

---

🎯 Overview

Chat blocks are designed to:

• Manage chat channels with full CRUD operations
• Handle message exchange and real-time communication
• Support secure file attachments with signed URLs and malicious file type filtering
• Stream messages in real-time via WebSocket with MongoDB change streams
• Track read states to mark which messages users have read in channels
• Provide message template management for reusable content
• Provide subscription management for notifications
• Support multi-channel communication
• Enable chat administration with comprehensive controls

---

📦 Block Types

🔍 Schemas

JSON Schema definitions for chat data validation:

• ChatChannelIcon: TypeScript type for channel icon metadata
• chatChannelSchema: Base channel entity structure
• createChatChannelSchema: Channel creation validation
• updateChatChannelSchema: Channel modifications
• getChatChannelSchema: Channel retrieval
• deleteChatChannelSchema: Channel deletion
• findChatChannelsSchema: Channel search with filtering and pagination
• getChannelMessagesSchema: Channel messages retrieval validation
• chatMessageSchema: Message entity structure
• chatMessageAttachmentSchema: Message attachment validation with objectId and type
• createChatMessageAttachmentSchema: Attachment creation validation for adding files to existing messages
• deleteChatMessageAttachmentSchema: Attachment deletion validation with messageId and attachmentId path parameters
• createChatMessageSchema: Message creation validation with attachments support
• updateChatMessageSchema: Message modifications
• getChatMessageSchema: Message retrieval
• deleteChatMessageSchema: Message deletion
• findChatMessagesSchema: Message search with filtering and pagination
• channelIdQueryParameter: WebSocket query parameter for channel ID
• streamChatMessagesSchema: Real-time message streaming validation
• chatMessageTemplateSchema: Message template entity structure
• createChatMessageTemplateSchema: Message template creation validation
• getChatMessageTemplateSchema: Message template retrieval validation
• updateChatMessageTemplateSchema: Message template modifications
• deleteChatMessageTemplateSchema: Message template deletion validation
• findChatMessageTemplatesSchema: Message template search with filtering and pagination
• findChatMessageTemplatesForOrganizationSchema: Organization-scoped message template search with pagination
• chatSubscriptionSchema: Subscription entity structure
• createChatSubscriptionSchema: Subscription creation validation
• getChatSubscriptionSchema: Subscription retrieval
• deleteChatSubscriptionSchema: Subscription deletion
• findChatSubscriptionsSchema: Subscription search with filtering and pagination
• chatChannelReadStateSchema: Channel read state entity structure
• upsertChatChannelReadStateSchema: Channel read state upsert validation

View Chat Schemas →

🔧 Blocks

Pure business logic functions for chat operations:

• Channel Operations: getChannelMessagesByChannelId - Retrieves all messages for a specific channel, generateChatChannelIconUploadUrl - Generates signed upload URLs for channel icon images, normalizeChatChannel - Normalizes chat channel data with icon file processing
• Message Operations: createChatMessage - Creates new chat message with attachments, getChatMessageById - Retrieves message by ID, findChatMessages - Finds chat messages with filtering
• Message Normalization: normalizeChatMessage - Normalizes single message, normalizeChatMessages - Normalizes multiple messages
• Message Attachments: generateChatMessageAttachmentUploadUrl - Generates signed upload URLs for message attachments with security filtering, createChatMessageAttachment - Adds attachments to existing messages, getChatMessageAttachmentById - Retrieves specific attachments by ID, deleteChatMessageAttachment - Deletes attachments from messages and storage
• Attachment Normalization: normalizeChatMessageAttachment - Normalizes single attachment with signed URL (integrated into main normalization functions)
• Message Streaming: streamChatMessages - Streams real-time messages via MongoDB change streams, normalizeChatMessage - Normalizes message objects, normalizeChatMessageStream - Normalizes message streams
• Message Templates: createChatMessageTemplate - Creates a new chat message template, getChatMessageTemplateById - Retrieves a template by its unique identifier, updateChatMessageTemplate - Updates an existing chat message template, findChatMessageTemplates - Finds chat message templates matching a filter, buildFilterToGetChatMessageTemplatesByOrganizationId - Builds organization-specific filter for template queries, deleteChatMessageTemplate - Deletes a chat message template from the database
• Channel Read States: createChatChannelReadState - Creates read state records, updateChatChannelReadState - Updates read state records, findChatChannelReadStates - Finds read states with filtering, buildChatChannelReadStateQuery - Builds read state queries, buildLastReadMessageQuery - Builds last read message queries, buildCreateChatChannelReadStatePayload - Builds create payload, buildUpdateChatChannelReadStatePayload - Builds update payload
• Error Classes: ChatChannelBlockError, ChatChannelUnknownError, ChatMessageBlockError, ChatMessageDbError, ChatMessageNotFoundBlockError, ChatMessageUnexpectedDBError, ChatMessageAttachmentNotFoundBlockError, ChatMessageUnauthorizedError, ChatMessageForbiddenError, ChatMessageNotFoundError, ChatMessageInvalidMessageError, ChatMessageUnknownError, ChatMessageBadRequestError, ChatChannelReadStateBlockError, ChatChannelReadStateNotFoundError, ChatChannelReadStateDatabaseError, ChatChannelReadStateUnknownError

View Chat Block Functions →

⚙️ Handlers

Core business logic for chat operations:

• Channel Operations: createChatChannel, getChatChannelById, findChatChannels, updateChatChannel, deleteChatChannel
• Channel Terminator Functions: createChatChannelTerminator, normalizeChatChannelTerminator, normalizeChatChannelsListTerminator, deleteChatChannelTerminator
• Message Operations: createChatMessage, getChatMessageById, findChatMessages, updateChatMessage, deleteChatMessage
• Message Terminator Functions: createChatMessageTerminator, normalizeChatMessageTerminator, normalizeChatMessagesListTerminator, deleteChatMessageTerminator
• Subscription Operations: createChatSubscription, getChatSubscriptionById, findChatSubscriptions, deleteChatSubscription
• Subscription Terminator Functions: createChatSubscriptionTerminator, normalizeChatSubscriptionTerminator, normalizeChatSubscriptionsListTerminator, deleteChatSubscriptionTerminator

View Chat Handlers →

🛣️ Routes

HTTP and WebSocket endpoint definitions for chat operations:

• Channel Routes: createChatChannelRoute, getChatChannelRoute, findChatChannelsRoute, updateChatChannelRoute, deleteChatChannelRoute, getChannelMessagesRoute, getChatChannelIconUploadUrlRoute
• Message Routes: createChatMessageRoute, getChatMessageRoute, findChatMessagesRoute, updateChatMessageRoute, deleteChatMessageRoute, getChatMessageAttachmentUploadUrlRoute, createChatMessageAttachmentRoute, deleteChatMessageAttachmentRoute, streamChatMessagesRoute (WebSocket)
• Message Template Routes: createChatMessageTemplateRoute, getChatMessageTemplateRoute, updateChatMessageTemplateRoute, findChatMessageTemplatesRoute, findChatMessageTemplatesForOrganizationRoute, deleteChatMessageTemplateRoute
• Subscription Routes: createChatSubscriptionRoute, getChatSubscriptionRoute, findChatSubscriptionsRoute, deleteChatSubscriptionRoute
• Channel Read State Routes: upsertChatChannelReadStateRoute

View Chat Routes →

🚀 Features

Composed chat features for easy integration:

• Channel Features: createChannelFeature, getChannelFeature, findChannelsFeature, updateChannelFeature, deleteChannelFeature, getChannelMessagesFeature, getChannelIconUploadUrlFeature
• Message Features: createChatMessageFeature, getChatMessageFeature, findChatMessagesFeature, updateChatMessageFeature, deleteChatMessageFeature, getChatMessageAttachmentUrlFeature, createChatMessageAttachmentFeature, deleteChatMessageAttachmentFeature, streamChatMessagesFeature (WebSocket)
• Message Template Features: createChatMessageTemplateFeature, getChatMessageTemplateFeature, updateChatMessageTemplateFeature, findChatMessageTemplatesFeature, findChatMessageTemplatesForOrganizationFeature, deleteChatMessageTemplateFeature
• Subscription Features: createChatSubscriptionFeature, getChatSubscriptionFeature, findChatSubscriptionsFeature, deleteChatSubscriptionFeature
• Channel Read State Features: upsertChatChannelReadStateFeature

View Chat Features →

✅ Validators

Validation functions for chat operations:

• channelExists: Validates that a chat channel exists in the database
• hasSubscription: Validates that an identity is subscribed to a channel
• ownsSubscription: Validates subscription ownership by the subscribed identity
• ownsChannel: Validates channel ownership by the identity
• ownsMessage: Validates message ownership by the sender
• hasOrganizationAccessToMessageTemplate: Validates org role-based access to message templates
• validateChannelAccess (deprecated): Legacy access validator; replaced by ownsChannel
• validateMessageAccess (deprecated): Legacy access validator; replaced by ownsMessage

View Chat Validators →

---

🔗 Related Documentation

• Chat Schemas - Chat data validation and contracts
• Chat Handlers - Chat business logic functions
• Chat Routes - Chat HTTP endpoint definitions
• Chat Features - Complete chat feature documentation
• Chat Validators - Chat validation functions