Search Local Messages

tip

• The message search feature only supports searching messages stored in the local database.
• The SDK supports ultra group local message search starting from version 5.3.4.
• RC provides IM Server APIs for searching ultra group historical messages. See the server-side documentation Search Ultra Group Messages for details.

You can use the IMLib SDK's search interfaces to search for qualified message lists in conversations based on keywords, message types, and other conditions, with support for time-range searches. You can also search for qualified message lists in specified conversations by user userId.

Messages that support keyword search need to implement the MessageContent's getSearchableWord method:

• Among built-in message types, text messages (TextMessage), file messages (FileMessage), and rich content messages (RichContentMessage) have implemented the MessageContent#getSearchableWord method by default.
• Custom message types can also support keyword search, which requires you to implement it yourself by referring to the documentation. See Custom Message Types for details.

Search Conversations

Search all local conversations by keyword. Returns a list of qualified conversations SearchConversationResult. Note that in ultra group services, a single conversation (conversation) corresponds to only one ultra group channel.

Interface

ChannelClient.getInstance().searchConversationForAllChannel(keyword, conversationTypes, messageTypeObjectNames,callback);

Parameter Description

If the search conditions and results involve multiple conversation types, you can classify or filter them using the conversation type (ConversationType) field in the returned Conversation object.

Parameter	Type	Description
keyword	String	Search keyword
conversationTypes	Conversation.ConversationType[]	List of conversation types, including ConversationType, such as ConversationType.ULTRA_GROUP, ConversationTypes.PRIVATE, ConversationTypes.GROUP.
objName	String[]	List of message types, supporting only built-in types RC:TxtMsg (text message), RC:FileMsg (file message), and RC:ImgTextMsg (rich content message) by default.
callback	IRongCoreCallback.ResultCallback<List<SearchConversationResult>>	Callback. The search result is a list of SearchConversationResult. Note that for ultra groups, a single conversation (conversation) corresponds to one ultra group channel.

Example Code

String keyword = "Search keyword";
Conversation.ConversationTypes[] conversationTypes = {ConversationType.ULTRA_GROUP};
String[] messageTypeObjectNames = {"RC:TxtMsg"};

ChannelClient.getInstance().searchConversationForAllChannel(keyword, conversationTypes, messageTypeObjectNames,
    new IRongCoreCallback.ResultCallback<List<SearchConversationResult>>() {

    @Override
    public void onSuccess(List<SearchConversationResult> searchConversationResults) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode) {

    }
});

Search Messages in a Single Channel

After obtaining a list of conversations containing keywords, you can search for qualified messages in a specified single conversation. When implementing ultra group message search, you can first obtain a list of qualified ultra group conversations by searching conversations, then search for qualified messages in the specified channel.

Searching messages in a single channel requires the app to provide both the ultra group ID (targetId) and the channel ID (channelId).

Search Messages in a Specified Channel by Keyword

You can search for messages in a specified channel conversation in local storage based on keywords, supporting searches for historical messages before a specified time point. The callback returns a paginated list of messages containing the specified keyword.

Interface

ChannelClient.getInstance().searchMessages(conversationType, targetId, channelId, keyword, count, beginTime,callback);

Parameter Description

Parameter	Type	Description
conversationType	ConversationType	Conversation type. For ultra group conversations, pass ConversationType.ULTRA_GROUP.
targetId	String	Ultra group ID.
channelId	String	Ultra group channel ID.
keyword	String	Search keyword.
count	int	Number of items per page. It is recommended to limit this to 100 messages. Passing 0 returns all found messages.
beginTime	long	Start time for the search. Passing 0 starts the search from the latest message. Non-zero values start the search from this time backward.
callback	IRongCoreCallback.ResultCallback<List<Message>>	Callback. The search result is a list of Message.

Example Code

ConversationType conversationType = ConversationType.ULTRA_GROUP;
String targetId = "Ultra group ID";
String channelId = "Ultra group channel ID";
String keyword = "Search keyword";
int count = 20;
long beginTime = 122323344;

ChannelClient.getInstance().searchMessages(conversationType, targetId, channelId, keyword, count, beginTime,
    new IRongCoreCallback.ResultCallback<List<Message>>() {

    @Override
    public void onSuccess(List<Message> messages) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode) {

    }
});

Search Messages in a Specified Channel by Keyword and Time Range

The SDK allows you to search for local messages in a specified ultra group channel within a specified time range that match the keyword. The callback returns a list of messages that meet the search criteria.

Interface

ChannelClient.getInstance().searchMessages(conversationType, targetId, channelId, keyword, startTime, endTime, offset, limit,callback);

Parameter Description

The limit parameter controls the number of search results returned, with a valid range of [1-100]. Values exceeding 100 default to the maximum of 100.

Parameter	Type	Description
conversationType	ConversationType	Conversation type. For ultra group conversations, pass ConversationType.ULTRA_GROUP.
targetId	String	Ultra group ID.
channelId	String	Ultra group channel ID.
keyword	String	Search keyword.
startTime	long	Start time.
endTime	long	End time.
offset	int	Offset.
limit	int	Number of search results to return. limit must be greater than 0. The maximum is 100. Values exceeding 100 default to 100 messages.
callback	IRongCallback.ResultCallback<List<Message>>	Callback. The search result is a list of Message.

Example Code

ConversationType conversationType = ConversationType.ULTRA_GROUP;
String targetId = "Ultra group ID";
String channelId = "Ultra group channel ID";
String keyword = "123";
long startTime = 0;
long endTime = 1585815113;
int offset = 0;
int limit = 80;

ChannelClient.getInstance().searchMessages(conversationType, targetId, channelId, keyword, startTime, endTime, offset, limit,
    new IRongCoreCallback.ResultCallback<List<Message>>(){

    @Override
    public void onSuccess(List<Message> messages) {

    }

    @Override
     public void onError(IRongCoreEnum.CoreErrorCode e) {

    }
});

Search Messages in a Specified Channel by User ID

You can search for messages sent by a specified user userId in a specified ultra group conversation, supporting searches for local historical messages before a specified time point. The callback returns a list of messages that meet the search criteria.

Interface

ChannelClient.getInstance().searchMessagesByUser(conversationType, targetId, channelId, userId, count, beginTime,callback);

Parameter Description

Parameter	Type	Description
conversationType	ConversationType	Conversation type. For ultra group conversations, pass ConversationType.ULTRA_GROUP.
targetId	String	Ultra group ID.
channelId	String	Ultra group channel ID.
userId	String	The user ID to query.
count	int	Number of search results to return. Maximum value is 100. If exceeded, defaults to returning 100 messages.
beginTime	long	Start time for query. Pass 0 to search from the latest message. Pass a non-zero value to search backward from this timestamp.
callback	IRongCallback.ResultCallback<List<Message>>	Callback. Returns a list of Message objects as search results.

Sample Code

ConversationType conversationType = ConversationType.ULTRA_GROUP;
String targetId = "ultra group ID";
String channelId = "ultra group channel ID";
String userId = "user Id to query";
int count = 20;
long beginTime = 1585815113;

ChannelClient.getInstance().searchMessagesByUser(conversationType, targetId, channelId, userId, count, beginTime,
    new IRongCoreCallback.ResultCallback<Message>() {

    @Override
    public void onSuccess(List<Message> messages) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode) {

    }
});

Searching Messages Across Multiple Channels in an Ultra Group

If an app needs to search messages in a specified ultra group and already has the ultra group ID (targetId), it can directly use the following interfaces to search locally received and stored messages. Search results may include messages from multiple channels.

Searching All Channels in an Ultra Group by Keyword

Searches locally stored messages in a specified ultra group, supporting searches for historical messages before a specified timestamp. Returns paginated results containing the specified keyword.

Interface

ChannelClient.getInstance().searchMessageForAllChannel(targetId, conversationType, keyword, count, timestamp,callback);

Parameter Description

Parameter	Type	Description
targetId	String	Ultra group ID.
conversationType	ConversationType	Conversation type. For ultra group conversations, pass ConversationType.ULTRA_GROUP.
keyword	String	Search keyword.
count	int	Number of results per page (recommended maximum: 100). Pass 0 to return all matching messages.
beginTime	long	Start time for query. Pass 0 to search from the latest message. Pass a non-zero value to search backward from this timestamp.
callback	IRongCoreCallback.ResultCallback<List<Message>>	Callback. Returns a list of Message objects as search results.

Sample Code

String targetId = "ultra group ID";
ConversationType conversationType = ConversationType.ULTRA_GROUP;
String keyword = "search keyword";
int count = 20;
long timestamp = "122323344";

ChannelClient.getInstance().searchMessageForAllChannel(targetId, conversationType, keyword, count, timestamp,
    new IRongCoreCallback.ResultCallback<List<Message>>() {

    @Override
    public void onSuccess(List<Message> messages) {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode) {

    }
});

Searching All Channels in an Ultra Group by Keyword Within a Specified Time Range

When searching locally stored messages in a specified ultra group, the SDK supports restricting keyword searches to a specified time range. Returns paginated results containing both the specified keyword and meeting the time range requirements.

Interface

ChannelClient.getInstance().searchMessageByTimestampForAllChannel(conversationType, targetId, keyword, startTime, endTime, offset, limit,callback);

Parameter Description

The limit parameter controls the number of search results returned, with a valid range of [1-100]. Values exceeding 100 will default to the maximum of 100.

Parameter	Type	Description
targetId	String	Ultra group ID
conversationType	ConversationType	Conversation type. For ultra group conversations, pass ConversationType.ULTRA_GROUP.
keyword	String	Search keyword
startTime	long	Start timestamp
endTime	long	End timestamp
offset	int	Offset
limit	int	Number of search results to return (must be >0). Maximum value is 100. If exceeded, defaults to returning 100 messages.
callback	IRongCallback.ResultCallback<List<Message>>	Callback. Returns a list of Message objects as search results.

Sample Code

String targetId = "ultra group ID";
ConversationType conversationType = ConversationType.ULTRA_GROUP;
String keyword = "123";
long startTime = 0;
long endTime = 1585815113;
int offset = 0;
int limit = 80;

ChannelClient.getInstance().searchMessageByTimestampForAllChannel(conversationType, targetId, keyword, startTime, endTime, offset, limit,
    new IRongCoreCallback.ResultCallback<List<Message>>(){

    @Override
    public void onSuccess(List<Message> messages) {

    }

    @Override
     public void onError(IRongCoreEnum.CoreErrorCode e) {

    }
});

Searching Multiple Channels in an Ultra Group by Keyword

tip

This method is available starting from SDK version 5.6.2.

Ensure valid Channel ID arrays are passed. The Channel ID array cannot be empty, must contain no more than 50 IDs, and all IDs must be valid (alphanumeric characters). Empty Channel IDs are not supported. Supports searching from the latest message or messages before startTime. Each search returns a maximum of 100 messages. For additional results, set startTime to the timestamp of the last message in the returned array and call the interface again.

Interface

/**
 * Search local historical messages across multiple channels in a specified ultra group by keyword
 *
 * <p>Note: For custom messages to be searchable, implement the {@link MessageContent#getSearchableWord()} method in the custom message class.
 *
 * @param conversationType Specified conversation type.
 * @param targetId Specified conversation ID.
 * @param channelIds Business identifiers for message channels (0 < channelIds.length <= 50, returns {@link
 *     IRongCoreEnum.CoreErrorCode#RC_INVALID_PARAMETER_CHANNEL_ID} if invalid).
 * @param keyword Search keyword (0 < length <= 1000).
 * @param startTime Start timestamp for query (pass 0 to search from latest message, otherwise searches backward from this timestamp).
 * @param limit Number of search results to return {@code 0 < limit <= 100}. If {@code limit > 100}, defaults to 100.
 * @param resultCallback Search result callback.
 * @since 5.6.2
 */
public abstract void searchMessagesForChannels(
        final Conversation.ConversationType conversationType,
        final String targetId,
        final String[] channelIds,
        final String keyword,
        final long startTime,
        final int limit,
        final IRongCoreCallback.ResultCallback<List<Message>> resultCallback);

Search Local History Messages by Sender User ID in Multiple Channels of a Specified Ultra Group

tip

This method has been available since SDK version 5.6.2.

Ensure valid Channel ID arrays are passed. The Channel ID array cannot be empty, the number of IDs cannot exceed 50, and all Channel IDs in the array must be valid (case-sensitive letters and numbers). Empty Channel IDs are not supported. Supports searching from the latest messages or messages older than startTime. Each search returns a maximum of 100 messages. If more messages exist, you can set startTime to the timestamp of the last message in the retrieved message array and continue calling the interface.

Interface

/**
 * Search messages in specified conversations based on conversation ID, business identifier, user ID, etc.
 *
 * <p>Note: For custom messages to be searchable, implement the {@link MessageContent#getSearchableWord()} method in the custom message.
 *
 * @param conversationType The specified conversation type.
 * @param targetId The specified conversation ID.
 * @param channelIds The business identifiers of the conversation to which the messages belong. (0 < channelIds.length <= 50, otherwise returns {@link
 *     IRongCoreEnum.CoreErrorCode#RC_INVALID_PARAMETER_CHANNEL_ID})
 * @param userId The user ID.
 * @param startTime The start time for querying records. Pass 0 to search from the latest messages, searching backward from this time.
 * @param limit The number of search results to return {@code 0 < limit <= 100}. If {@code limit > 100}, returns 100.
 * @param resultCallback The search result callback.
 * @since 5.6.2
 */
public abstract void searchMessagesByUserForChannels(
        final Conversation.ConversationType conversationType,
        final String targetId,
        final String[] channelIds,
        final String userId,
        final long startTime,
        final int limit,
        final IRongCoreCallback.ResultCallback<List<Message>> resultCallback);

Search Local History Messages by Sender User ID in All Channels of a Specified Ultra Group

tip

This method has been available since SDK version 5.6.2.

Supports searching from the latest messages or messages older than startTime. Each search returns a maximum of 100 messages. If more messages exist, you can set startTime to the timestamp of the last message in the retrieved message array and continue calling the interface.

Interface

/**
 * Search messages in specified conversations based on conversation ID, user ID, etc. (Includes all ChannelIds)
 *
 * <p>Note: For custom messages to be searchable, implement the {@link MessageContent#getSearchableWord()} method in the custom message.
 *
 * @param conversationType The specified conversation type.
 * @param targetId The specified conversation ID.
 * @param userId The user ID.
 * @param startTime The start time for querying records. Pass 0 to search from the latest messages, searching backward from this time.
 * @param limit The number of search results to return {@code 0 < limit <= 100}. If {@code limit > 100}, returns 100.
 * @param resultCallback The search result callback.
 * @since 5.6.2
 */
public abstract void searchMessagesByUserForAllChannel(
        final Conversation.ConversationType conversationType,
        final String targetId,
        final String userId,
        final long startTime,
        final int limit,
        final IRongCoreCallback.ResultCallback<List<Message>> resultCallback);