Class ChatConversation

The conversation class, which defines one-to-one conversations, group conversations, and chat room conversations.

Each type of conversation involves messages that are sent and received.

You can get the conversation name by conversation type:

One-to-one chat: See ChatUserInfoManager.fetchUserInfoById.
Group chat: See ChatGroup.getGroupWithId.
Chat room: See ChatRoom.fetchChatRoomInfoFromServer.

Constructors

constructor

new ChatConversation(
    params: {
        convId: string;
        convType: ChatConversationType;
        ext?: any;
        isChatThread?: boolean;
        isPinned?: boolean;
        marks?: ChatConversationMarkType[];
        pinnedTime?: number;
    },
): ChatConversation
Parameters
- params: {
      convId: string;
      convType: ChatConversationType;
      ext?: any;
      isChatThread?: boolean;
      isPinned?: boolean;
      marks?: ChatConversationMarkType[];
      pinnedTime?: number;
  }
Returns ChatConversation

Properties

convId

convId: string

The conversation ID.

convType

convType: ChatConversationType

The conversation type.

`Optional`ext

ext?: any

The conversation extension.

isChatThread

isChatThread: boolean

Whether the current conversation is a thread conversation.

true: Yes.
false: No.

Note

This parameter is valid only for group chat.

`Optional`isPinned

isPinned?: boolean

Whether the conversation is pinned:

true: Yes.
(Default) false: No.

`Optional`marks

marks?: ChatConversationMarkType[]

The conversation marks.

`Optional`pinnedTime

pinnedTime?: number

The UNIX timestamp when the conversation is pinned. The unit is millisecond. This value is 0 when the conversation is not pinned.

Methods

deleteAllMessages

deleteAllMessages(): Promise<void>
Deletes all the messages of the conversation.

This method deletes all the messages of the conversation from both the memory and local database.

Returns Promise<void>
Throws
A description of the exception. See ChatError.

deleteMessage

deleteMessage(msgId: string): Promise<void>
Deletes a message from the local database.
Parameters
- msgId: string
  The ID of message to delete.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

deleteMessagesWithTimestamp

deleteMessagesWithTimestamp(
params: { endTs: number; startTs: number },
): Promise<void>
Deletes messages sent or received in a certain period from the local database.
Parameters
- params: { endTs: number; startTs: number }
Returns Promise<void>
Params
params
- startTs: The starting UNIX timestamp for message deletion. The unit is millisecond.
- endTs: The end UNIX timestamp for message deletion. The unit is millisecond.
Throws
A description of the exception. See ChatError.

fetchPinnedMessages

fetchPinnedMessages(): Promise<ChatMessage[]>
Gets the pinned messages in the conversation from the server.

Returns Promise<ChatMessage[]>
The list of pinned messages. If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

getLatestMessage

getLatestMessage(): Promise<ChatMessage | undefined>
Gets the latest message from the conversation.

Returns Promise<ChatMessage | undefined>
The message instance. The SDK returns undefined if the message does not exist.

Throws
A description of the exception. See ChatError.

getLatestReceivedMessage

getLatestReceivedMessage(): Promise<ChatMessage | undefined>
Gets the latest message received in the conversation.

Returns Promise<ChatMessage | undefined>
The message instance. The SDK returns undefined if the message does not exist.

Throws
A description of the exception. See ChatError.

getMessageCount

getMessageCount(): Promise<number>
Gets the count of messages in the conversation.

Returns Promise<number>
The count of messages.

Throws
A description of the exception. See ChatError.

getMessages

getMessages(
    startMsgId: string,
    direction?: ChatSearchDirection,
    loadCount?: number,
): Promise<ChatMessage[]>
Gets messages of a certain quantity in a conversation from the local database.

Note

The obtained messages will also join the existing messages of the conversation stored in the memory.
Parameters
- startMsgId: string
  The starting message ID for query. After this parameter is set, the SDK retrieves messages, starting from the specified one, according to the message search direction. If this parameter is set an empty string, the SDK retrieves messages according to the message search direction while ignoring this parameter. - If direction is set as ChatSearchDirection.UP, the SDK retrieves messages, starting from the latest one, in the descending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them. - If direction is set as ChatSearchDirection.DOWN, the SDK retrieves messages, starting from the oldest one, in the ascending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- direction: ChatSearchDirection = ChatSearchDirection.UP
  The message search direction. See ChatSearchDirection.
  
  (Default) ChatSearchDirection.UP: Messages are retrieved in the descending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
  
  ChatSearchDirection.DOWN: Messages are retrieved in the ascending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- loadCount: number = 20
  The maximum number of messages to retrieve each time. The value range is [1,400].
Returns Promise<ChatMessage[]>
The message list (excluding the ones with the starting or ending timestamp). If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

Deprecated
2024-04-17 This method is deprecated. Use getMsgs instead.

getMessagesWithKeyword

getMessagesWithKeyword(
    keywords: string,
    direction?: ChatSearchDirection,
    timestamp?: number,
    count?: number,
    sender?: string,
): Promise<ChatMessage[]>
Gets messages with keywords in a conversation in the local database.
Parameters
- keywords: string
  The keywords for query.
- direction: ChatSearchDirection = ChatSearchDirection.UP
  The message search direction. See ChatSearchDirection.
  
  (Default) ChatSearchDirection.Up: Messages are retrieved in the descending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
  
  ChatSearchDirection.Down: Messages are retrieved in the ascending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- timestamp: number = -1
  The starting Unix timestamp in the message for query. The unit is millisecond. After this parameter is set, the SDK retrieves messages, starting from the specified one, according to the message search direction. If you set this parameter as a negative value, the SDK retrieves messages, starting from the current time, in the descending order of the the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- count: number = 20
  The maximum number of messages to retrieve each time. The value range is [1,400].
- Optionalsender: string
  The user ID or group ID for retrieval. Usually, it is the conversation ID.
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the one with the starting timestamp). If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

Deprecated
2024-04-17 This method is deprecated. Use getMsgsWithKeyword instead.

getMessagesWithMsgType

getMessagesWithMsgType(
    msgType: ChatMessageType,
    direction?: ChatSearchDirection,
    timestamp?: number,
    count?: number,
    sender?: string,
): Promise<ChatMessage[]>
Gets messages of a certain type that a specified user sends in a conversation.
Parameters
- msgType: ChatMessageType
  The message type. See ChatMessageType.
- direction: ChatSearchDirection = ChatSearchDirection.UP
  The message search direction. See ChatSearchDirection.
  
  (Default) ChatSearchDirection.UP: Messages are retrieved in the descending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
  
  ChatSearchDirection.DOWN: Messages are retrieved in the ascending of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- timestamp: number = -1
  The starting Unix timestamp in the message for query. The unit is millisecond. After this parameter is set, the SDK retrieves messages, starting from the specified one, according to the message search direction. If you set this parameter as a negative value, the SDK retrieves messages, starting from the current time, in the descending order of the timestamp included in them.
- count: number = 20
  The maximum number of messages to retrieve each time. The value range is [1,400].
- Optionalsender: string
  The user ID or group ID for retrieval. Usually, it is the conversation ID.
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the one with the starting timestamp). If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

Deprecated
2024-04-17 This method is deprecated. Use getMsgsWithMsgType instead.

getMessageWithTimestamp

getMessageWithTimestamp(
    startTime: number,
    endTime: number,
    direction?: ChatSearchDirection,
    count?: number,
): Promise<ChatMessage[]>
Gets messages that are sent and received in a certain period in a conversation in the local database.
Parameters
- startTime: number
  The starting Unix timestamp for search. The unit is millisecond.
- endTime: number
  The ending Unix timestamp for search. The unit is millisecond.
- direction: ChatSearchDirection = ChatSearchDirection.UP
  The message search direction. See ChatSearchDirection.
  
  (Default) ChatSearchDirection.UP: Messages are retrieved in the descending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
  
  ChatSearchDirection.DOWN: Messages are retrieved in the ascending order of the Unix timestamp (ChatOptions.sortMessageByServerTime) included in them.
- count: number = 20
  The maximum number of messages to retrieve each time. The value range is [1,400].
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the ones with the starting or ending timestamp). If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

Deprecated
2024-04-17 This method is deprecated. Use getMsgWithTimestamp instead.

getMsgs

getMsgs(
    params: {
        direction?: ChatSearchDirection;
        loadCount?: number;
        startMsgId: string;
    },
): Promise<ChatMessage[]>
Gets messages of a specified quantity in a conversation from the local database.

The retrieved messages will also be put in the conversation in the memory according to the timestamp included in them.

note If the conversation object does not exist, this method will create it.
Parameters
- params: { direction?: ChatSearchDirection; loadCount?: number; startMsgId: string }
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the one with the starting timestamp). If no message is obtained, an empty list is returned.
Params
Throws
A description of the exception. See ChatError.

getMsgsWithKeyword

getMsgsWithKeyword(
    params: {
        count?: number;
        direction?: ChatSearchDirection;
        keywords: string;
        searchScope?: ChatMessageSearchScope;
        sender?: string;
        timestamp?: number;
    },
): Promise<ChatMessage[]>
Gets messages that the specified user sends in a conversation in a certain period.

This method gets data from the local database.

note If the conversation object does not exist, this method will create it.
Parameters
- params: {
      count?: number;
      direction?: ChatSearchDirection;
      keywords: string;
      searchScope?: ChatMessageSearchScope;
      sender?: string;
      timestamp?: number;
  }
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the one with the starting timestamp). If no message is obtained, an empty list is returned.
Params
- keywords The keywords for query.
- direction The message search direction. See ChatSearchDirection.
- (Default) ChatSearchDirection.UP: Messages are retrieved in the descending order of the Unix timestamp included in them.
- ChatSearchDirection.DOWN: Messages are retrieved in the ascending order of the Unix timestamp included in them.
- timestamp The starting Unix timestamp in the message for query. The unit is millisecond. After this parameter is set, the SDK retrieves messages, starting from the specified one, according to the message search direction.
- searchScope The message search scope. See ChatMessageSearchScope. If you set this parameter as a negative value, the SDK retrieves messages, starting from the current time, in the descending order of the timestamp included in them.
- count The maximum number of messages to retrieve each time. The value range is [1,400].
- sender The user ID or group ID for retrieval. Usually, it is the conversation ID.
Throws
A description of the exception. See ChatError.

getMsgsWithMsgType

getMsgsWithMsgType(
    params: {
        count?: number;
        direction?: ChatSearchDirection;
        msgType: ChatMessageType;
        sender?: string;
        timestamp?: number;
    },
): Promise<ChatMessage[]>
Gets messages of a certain type in the conversation from the local database.

note If the conversation object does not exist, this method will create it.
Parameters
- params: {
      count?: number;
      direction?: ChatSearchDirection;
      msgType: ChatMessageType;
      sender?: string;
      timestamp?: number;
  }
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding the one with the starting timestamp). If no message is obtained, an empty list is returned.
Params
Throws
A description of the exception. See ChatError.

getMsgWithTimestamp

getMsgWithTimestamp(
    params: {
        count?: number;
        direction?: ChatSearchDirection;
        endTime: number;
        startTime: number;
    },
): Promise<ChatMessage[]>
Gets messages that are sent and received in a certain period in a conversation in the local database.

note If the conversation object does not exist, this method will create it.
Parameters
- params: {
      count?: number;
      direction?: ChatSearchDirection;
      endTime: number;
      startTime: number;
  }
Returns Promise<ChatMessage[]>
The list of retrieved messages (excluding with the ones with the starting or ending timestamp). If no message is obtained, an empty list is returned.
Params
Throws
A description of the exception. See ChatError.

getPinnedMessages

getPinnedMessages(): Promise<ChatMessage[]>
Gets the pinned messages in the conversation from the local database.

Returns Promise<ChatMessage[]>
The list of pinned messages. If no message is obtained, an empty list is returned.

Throws
A description of the exception. See ChatError.

getUnreadCount

getUnreadCount(): Promise<number>
Gets the count of unread messages in the conversation.

Returns Promise<number>
The count of unread messages.

Throws
A description of the exception. See ChatError.

markAllMessagesAsRead

markAllMessagesAsRead(): Promise<void>
Marks all messages as read.

Returns Promise<void>
Throws
A description of the exception. See ChatError.

markMessageAsRead

markMessageAsRead(msgId: string): Promise<void>
Marks a message as read.
Parameters
- msgId: string
  The message ID.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

name

name(): Promise<string | undefined>
Gets the conversation ID.

Returns Promise<string | undefined>
The conversation ID.

removeMessagesFromServerWithMsgIds

removeMessagesFromServerWithMsgIds(msgIds: string[]): Promise<void>
Deletes messages from the conversation (from both local storage and server).
Parameters
- msgIds: string[]
  The IDs of messages to delete from the current conversation.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

removeMessagesFromServerWithTimestamp

removeMessagesFromServerWithTimestamp(timestamp: number): Promise<void>
Deletes messages from the conversation (from both local storage and server).
Parameters
- timestamp: number
  The message timestamp in millisecond. The messages with the timestamp smaller than the specified one will be deleted.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

setConversationExtension

setConversationExtension(ext: { [key: string]: string | number }): Promise<void>
Sets the extension information of the conversation.
Parameters
- ext: { [key: string]: string | number }
  The extension information of the conversation. This parameter must be in the key-value format.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

updateMessage

updateMessage(msg: ChatMessage): Promise<void>
Updates a message in the local database.

After you modify a message, the message ID remains unchanged and the SDK automatically updates attributes of the conversation, like latestMessage.
Parameters
- msg: ChatMessage
  The message instance.
Returns Promise<void>
Throws
A description of the exception. See ChatError.

Class ChatConversation

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns ChatConversation

Properties

convId

convType

Optionalext

isChatThread

OptionalisPinned

Optionalmarks

OptionalpinnedTime

Methods

deleteAllMessages

Returns Promise<void>

Throws

deleteMessage

Parameters

Returns Promise<void>

Throws

deleteMessagesWithTimestamp

Parameters

Returns Promise<void>

Params

Throws

fetchPinnedMessages

Returns Promise<ChatMessage[]>

Throws

getLatestMessage

Returns Promise<ChatMessage | undefined>

Throws

getLatestReceivedMessage

Returns Promise<ChatMessage | undefined>

Throws

getMessageCount

Returns Promise<number>

Throws

getMessages

Parameters

Returns Promise<ChatMessage[]>

Throws

Deprecated

getMessagesWithKeyword

Parameters

Returns Promise<ChatMessage[]>

Throws

Deprecated

getMessagesWithMsgType

Parameters

Returns Promise<ChatMessage[]>

Throws

Deprecated

getMessageWithTimestamp

Parameters

Returns Promise<ChatMessage[]>

Throws

Deprecated

getMsgs

Parameters

Returns Promise<ChatMessage[]>

Params

Throws

getMsgsWithKeyword

Parameters

Returns Promise<ChatMessage[]>

Params

Throws

getMsgsWithMsgType

Parameters

Returns Promise<ChatMessage[]>

Params

Throws

getMsgWithTimestamp

Parameters

Returns Promise<ChatMessage[]>

`Optional`ext

`Optional`isPinned

`Optional`marks

`Optional`pinnedTime