Chats

The Chats module is responsible for managing chats. It provides actions to send, update, delete, and resend messages, as well as accessors to retrieve chat-related data. When the Chats module is integrated with the Room module, it enables users to seamlessly send and receive messages within a room, enriching the in-room communication experience.

• core
• user
• websocket

Initialization

const chats = new createChats({
 userModule: user,
 webSocketModule: webSocket,
 config: {
   host: 'chat.dev.zu.casa'
 }
});

Actions

joinChat

Action type (token: string): Promise<IChatContextReady>

Description The function allows a user to enter an existing chat, where it automatically displays past messages, helping the user get up to speed with the conversation’s history.

• token - a short-lived, server-issued token created on request that encodes the user’s permissions for the specific chat they’re joining.

Return value Returns a promise that resolves with the details of the chat context.

• ActionCallError - Can not perform this action (joinChat) while module is not connected with WebSocket.
• ActionCallError - Invalid token.
• ActionCallError - Expired token.
• ActionCallError - Cannot join to a chat that you have joined already.
• ActionCallError - That chat that you had been joining was left - you probably used leaveChat during loading join.

leaveChat

Action type (chatId: string): Promise<IChatContext>

Description This feature ends the user’s participation in the current chat session and stops the flow of messages from that chat, effectively removing the user from the conversation.

• chatId - the unique identifier for the chat that the user wishes to leave

Return value Returns a promise that resolves with the details of the chat context.

• ActionCallError - Can not perform this action (leaveChat) while module is not connected with WebSocket.
• ActionCallError - Cannot join to a chat that you have joined already.
• ActionCallError - That chat that you had been joining was left - you probably used leaveChat during loading join.

deleteMessage

Action type (chatId: string, messageId: string): Promise<IMessage>

Description This feature removes a specific message from the chat history, making it no longer visible to participants in the conversation.

• chatId - the unique identifier for the chat session where the message is located
• messageId - the specific identifier assigned to the message that needs to be deleted

Return value Returns a promise that resolves with the details of deleted message.

• ActionCallError - Can not perform this action (deleteMessage) while module is not connected with WebSocket.
• ActionCallError - Cannot delete a message from a chat you have not joined - use joinChat before.
• ActionCallError - Cannot delete a message from a chat that is loading - wait for joinChat to finish.
• ActionCallError - Cannot delete not existing a message - a message with this id does not exist in the selected chat.
• ActionCallError - You can only delete a message with status ready or interrupted.
• ActionCallError - The message is already being deleted.
• ActionCallError - The message is being updated. You can not delete it in that moment.

updateMessage

Action type (chatId: string, messageId: string, content: string): Promise<IMessage>

Description This feature allows a user to modify the content of an existing message in the chat, enabling corrections or updates to be made to the message after it has been sent.

• chatId - unique identifier of the chat containing the message to be updated
• messageId - identifier of the specific message that is to be altered
• content - the updated text or new content that will replace the original message

Return value Returns a promise that resolves with the details of updated message.

• ActionCallError - Can not perform this action (updateMessage) while module is not connected with WebSocket.
• ActionCallError - Cannot update a message from a chat you have not joined - use joinChat before.
• ActionCallError - Cannot update a message from a chat that is loading - wait for joinChat to finish.
• ActionCallError - Cannot update not existing a message - a message with this id does not exist in the selected chat.
• ActionCallError - You can only update a message with status ready.
• ActionCallError - The message is being deleted. You can not update it in that moment.
• ActionCallError - The message is being updated. You can not update it in that moment.

resendMessage

Action type (chatId: string, messageId: string): Promise<IMessage>

Description This feature is used to attempt to send a message again if the initial attempt to send it failed.

• chatId - the identifier of the chat where the message failed to send initially
• messageId - the identifier of the message that is to be resent.

Return value Returns a promise that resolves with the details of sent message.

• ActionCallError - Can not perform this action (resendMessage) while module is not connected with WebSocket.
• ActionCallError - Cannot send a message to a chat you have not joined - use joinChat before.
• ActionCallError - Cannot send a message to a chat that is loading - wait for joinChat to finish.
• ActionCallError - Cannot resend not existing a message - a message with this id does not exist in the selected chat.
• ActionCallError - You can only resend a message that failed to be send - it needs to have status interrupted.

sendMessage

Action type (chatId: string, content: string): Promise<IMessage>

Description This feature sends a new message from the user to the chat, allowing for real-time communication with other participants.

• chatId - the unique identifier for the chat to which the message will be sent
• content - the text of the message to be sent, with a maximum length of 256 characters.

Return value Returns a promise that resolves with the details of sent message.

• ActionCallError - Can not perform this action (sendMessage) while module is not connected with WebSocket.
• ActionCallError - Cannot send a message to a chat you have not joined - use joinChat before.
• ActionCallError - Cannot send a message to a chat that is loading - wait for joinChat to finish.

blockChatMember

Action type (chatId: string, chatMemberId: string, duration: number, reason?: string): Promise<void>

Description This feature restricts a specific user from participating in the chat, preventing them from sending messages or viewing new activity.

• chatId - identifier for the specific chat where the action will be applied.
• chatMemberId - unique identifier of the chat member who will be subject to the block.
• duration - time in minutes for which the block will be effective, with a value of 0 indicating a permanent block.
• reason - explanation or justification for implementing the block on the chat member.

Return value Returns a promise that finish after request sending.

• ActionCallError - Can not perform this action (blockChatMember) while module is not connected with WebSocket.

unblockChatMember

Action type (chatId: string, chatMemberId: string): Promise<void>

Description This feature reverses a previously set block on a user in the chat, restoring their ability to send messages and view new chat activity.

• chatId - identifier for the specific chat where the action will be applied.
• chatMemberId - unique identifier of the chat member who will be subject to the unblock.

Return value Returns a promise that finish after request sending.

• ActionCallError - Can not perform this action (unblockChatMember) while module is not connected with WebSocket.

muteChatMember

Action type (chatId: string, chatMemberId: string, duration: number, reason?: string): Promise<void>

Description This feature temporarily disables a user’s ability to send messages in the chat, while they can still view messages from other participants.

• chatId - identifier for the specific chat where the action will be applied.
• chatMemberId - unique identifier of the chat member who will be subject to the mute.
• duration - time in minutes for which the mute will be effective, with a value of 0 indicating a permanent mute.
• reason - explanation or justification for implementing the mute on the chat member.

Return value Returns a promise that finish after request sending.

• ActionCallError - Can not perform this action (muteChatMember) while module is not connected with WebSocket.

unmuteChatMember

Action type (chatId: string, chatMemberId: string): Promise<void>

Description This feature restores a previously muted user’s ability to send messages in the chat.

• chatId - identifier for the specific chat where the action will be applied.
• chatMemberId - unique identifier of the chat member who will be subject to the unmute.

Return value Returns a promise that finish after request sending.

• ActionCallError - Can not perform this action (unmuteChatMember) while module is not connected with WebSocket.

kickChatMember

Action type (chatId: string, chatMemberId: string, reason?: string): Promise<void>

Description This feature removes a user from the chat, blocking them from sending or seeing messages. However, the user has the option to re-enter the chat anytime afterward.

• chatId - identifier for the specific chat where the action will be applied.
• chatMemberId - unique identifier of the chat member who will be subject to the kick.
• reason - explanation or justification for implementing the kick on the chat member.

Return value Returns a promise that finish after request sending.

• ActionCallError - Can not perform this action (kickChatMember) while module is not connected with WebSocket.

Data (Getters)

chatsIds

Getter output type: IGetter<string[]>

Description This feature retrieves a list of identifiers for all the chats that a user is a part of.

getChatStatus

Getter output type: (chatId: string) => IGetter<'loading' | 'ready' | 'reloading' | undefined>

Description This feature retrieves the status of a chat, indicating its current state: ‘loading’ signifies the chat is initializing, ‘ready’ means the chat is available for use, and ‘reloading’ shows the chat is refreshing or updating its content.

getChatMessages

Getter output type: (chatId: string) => IGetter<IMessage[] | undefined>

Description This feature fetches the messages from a specified chat. If the chat does not exist or is not specified, the result will be undefined, indicating that no messages can be retrieved.

getChatMembersAmount

Getter output type: (chatId: string) => IGetter<bigint | undefined>

Description This feature returns the number of participants in a given chat.

getChatSyncStatuses

Getter output type: (chatId: string) => IGetter<IChatContext['syncStatuses'] | undefined>

Description This function returns the synchronization status of a chat, which can be ‘idle’ if there are no current sync processes, ‘loading’ if the chat is in the process of synchronizing, or it may return undefined if the chat does not exist or the status cannot be determined.

isChatSyncing

Getter output type: (chatId: string) => IGetter<boolean>

Description This function checks if a chat is currently in the process of synchronizing data, such as messages or updates. It returns a boolean value indicating the syncing state: true if the chat is syncing, or false if it is not.

getClientChatMemberMetadata

Getter output type: (chatId: string) => IGetter<{ [key: string]: string } | undefined>

Description This feature retrieves metadata specific to a user within a chat, such as their role, status, or any custom attributes that define their participation in the chat.

getClientChatMemberRestrictions

Getter output type: (chatId: string) => IGetter<Restriction[] | undefined>

Description This feature obtains information about any restrictions placed on a user’s actions within a chat, detailing the limitations on their ability to send messages or perform other chat-related activities.