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.

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 getSearchableWords method of the RCMessageCoding protocol:

• Built-in message types such as text messages (RCTextMessage), file messages (RCFileMessage), and rich content messages (RCRichContentMessage) have implemented the getSearchableWords method of the RCMessageCoding protocol by default.
• Custom message types can also support keyword search by implementing the getSearchableWords method. See Custom Message Types for details.

Search Conversations

Search all local conversations by keyword. Returns a list of qualified search results (RCSearchConversationResult). Note that in ultra group business, a single conversation (conversation) corresponds to only a single ultra group channel.

Interface Prototype

- (void)searchConversations:(NSArray<NSNumber *> *)conversationTypeList
                  channelId:(nullable NSString *)channelId
                messageType:(NSArray<NSString *> *)objectNameList
                    keyword:(NSString *)keyword
                 completion:(nullable void(^)(NSArray<RCSearchConversationResult *> * _Nullable results))completion;

Parameter Description

Parameter	Type	Description
conversationTypeList	NSArray	Conversation type list containing RCConversationType. For ultra groups, pass ConversationType_ULTRAGROUP.
channelId	NSString	Ultra group channel ID
objectNameList	NSArray	Message type list. By default, only built-in types RC:TxtMsg (text message), RC:FileMsg (file message), and RC:ImgTextMsg (rich content message) are supported.
keyword	NSString	Keyword. Cannot be empty.
completion	Block	Async callback. Returns a list of RCSearchConversationResult in results. Note that in ultra group business, a single conversation (conversation) corresponds to only a single ultra group channel.

Example Code

NSArray *conversationTypeList = @[@(ConversationType_ULTRAGROUP)];
NSArray *objectNameList = @[@"RC:TxtMsg"];

[[RCChannelClient sharedChannelManager] searchConversations:@[ @(ConversationType_ULTRAGROUP) ]
                channelId:@"channelId"
                messageType:objectNameList
                    keyword:@"search keyword"
                 completion:^(NSArray<RCSearchConversationResult *> * _Nullable results) {
                //Async callback
        }];

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. For ultra group message search, you can first get 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 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 by keyword, supporting searches for historical messages before a specified time point. The callback returns a paginated list of messages containing the specified keyword.

- (void)searchMessages:(RCConversationType)conversationType
              targetId:(NSString *)targetId
             channelId:(nullable NSString *)channelId
               keyword:(NSString *)keyword
                 count:(int)count
             startTime:(long long)startTime
            completion:(nullable void(^)(NSArray<RCMessage *> * _Nullable messages))completion;

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. For ultra group conversations, pass ConversationType_ULTRAGROUP.
targetId	NSString	Ultra group ID.
channelId	NSString	Ultra group channel ID.
keyword	NSString	Keyword. Passing empty defaults to searching all qualified messages.
count	int	Maximum number of queries.
startTime	long long	Start time for query records. Pass 0 to start searching from the latest message. Non-zero values search backward from this time.
completion	Block	Async callback. Returns a list of matched RCMessage in messages.

[[RCChannelClient sharedChannelManager] searchMessages:ConversationType_ULTRAGROUP
    targetId:@"ultra group ID"
    channelId:@"ultra group channel ID"
    keyword:searchText
    count:50
    startTime:0
    completion:^(NSArray<RCMessage *> * _Nullable messages) {
    //Async callback
}];

Search Messages in a Specified Channel by Keyword and Time Range

You can 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 Prototype

- (void)searchMessages:(RCConversationType)conversationType
              targetId:(NSString *)targetId
             channelId:(nullable NSString *)channelId
               keyword:(NSString *)keyword
                 count:(int)count
             startTime:(long long)startTime
            completion:(nullable void(^)(NSArray<RCMessage *> * _Nullable messages))completion;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. For ultra group conversations, pass ConversationType_ULTRAGROUP.
targetId	NSString	Ultra group ID.
channelId	NSString	Ultra group channel ID.
keyword	NSString	Keyword. Passing empty defaults to searching all qualified messages.
startTime	long long	Start time for query records. Pass 0 to start searching from the latest message. Non-zero values search backward from this time.
endTime	long long	End time.
offset	int	Offset. Must be ≥ 0.
limit	int	Number of search results to return. Must be > 0. Maximum is 100. Values over 100 default to 100.
completion	Block	Async callback. Returns a list of matched RCMessage in messages.

Example Code

[[RCChannelClient sharedChannelManager] searchMessages:ConversationType_ULTRAGROUP
    targetId:@"ultra group ID"
    channelId:@"ultra group channel ID"
    keyword:searchText
    startTime:startTime
    endTime:endTime
    offset:0
    limit:100
    completion:^(NSArray<RCMessage *> * _Nullable messages) {
    //Async callback
}];

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 Prototype

- (void)searchMessages:(RCConversationType)conversationType
              targetId:(NSString *)targetId
             channelId:(nullable NSString *)channelId
                userId:(NSString *)userId
                 count:(int)count
             startTime:(long long)startTime
            completion:(nullable void(^)(NSArray<RCMessage *> * _Nullable messages))completion;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. For ultra group conversations, pass ConversationType_ULTRAGROUP.
targetId	NSString	Ultra group targetId.
channelId	NSString	Ultra group channel ID.
userId	NSString	User userId to search.
count	int	Maximum number of queries.
startTime	long long	Start time for query records. Pass 0 to start searching from the latest message. Non-zero values search backward from this time.
completion	Block	Async callback. Returns a list of matched RCMessage in messages.

Example Code

[[RCChannelClient sharedChannelManager] searchMessages:ConversationType_ULTRAGROUP
    targetId:@"receiver id"
    channelId:@"ultra group channel ID"
    userId:@"userId"
    count:50
    startTime:0
    completion:^(NSArray<RCMessage *> * _Nullable messages) {
    //Async callback
}];

Search Messages Across Multiple Channels in an Ultra Group

Search Local Messages Across All Channels in an Ultra Group by Keyword

Interface Description

- (void)searchMessagesForAllChannel:(RCConversationType)conversationType
                           targetId:(NSString *)targetId
                            keyword:(NSString *)keyword
                              count:(int)count
                          startTime:(long long)startTime
                         completion:(nullable void(^)(NSArray<RCMessage *> * _Nullable messages))completion;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Use ConversationType_ULTRAGROUP for ultra group conversations.
targetId	NSString	Ultra group targetId.
keyword	NSString	Search keyword. Pass empty string to search all matching messages.
count	int	Maximum number of messages to return.
startTime	long long	Start timestamp for search. Pass 0 to search from latest messages. Non-zero values search backwards from this timestamp.
completion	Block	Asynchronous callback. Returns matched RCMessage list in messages.

Sample Code

[[RCChannelClient sharedChannelManager] searchMessagesForAllChannel:ConversationType_ULTRAGROUP
    targetId:@"ultra group ID"
    keyword:searchText
    count:50
    startTime:0
    completion:^(NSArray<RCMessage *> * _Nullable messages) {
    //Async callback
}];

Search Local Messages Across All Channels in an Ultra Group by Keyword Within Specified Time Range

Interface Prototype

- (void)searchMessagesForAllChannel:(RCConversationType)conversationType
                           targetId:(NSString *)targetId
                            keyword:(NSString *)keyword
                          startTime:(long long)startTime
                            endTime:(long long)endTime
                             offset:(int)offset
                              limit:(int)limit
                         completion:(nullable void(^)(NSArray<RCMessage *> * _Nullable messages))completion;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Use ConversationType_ULTRAGROUP for ultra group conversations.
targetId	NSString	Ultra group targetId.
keyword	NSString	Search keyword. Pass empty string to search all matching messages.
startTime	long long	Start timestamp for search. Pass 0 to search from latest messages. Non-zero values search backwards from this timestamp.
endTime	long long	End timestamp.
offset	int	Offset value. Must be ≥ 0.
limit	int	Number of search results to return. Must be > 0. Maximum is 100. Values exceeding 100 will default to 100.
completion	Block	Asynchronous callback. Returns matched RCMessage list in messages.

Sample Code

[[RCChannelClient sharedChannelManager] searchMessagesForAllChannel:ConversationType_ULTRAGROUP
    targetId:@"ultra group targetId"
    keyword:searchText
    startTime:startTime
    endTime:endTime
    offset:0
    limit:100
    completion:^(NSArray<RCMessage *> * _Nullable messages) {
    //Async callback
}];

Search Local Messages Across Multiple Channels in an Ultra Group by Keyword

tip

Available since SDK v5.6.2.

Interface Prototype

- (void)searchMessagesForChannels:(RCConversationType)conversationType
                         targetId:(NSString *)targetId
                       channelIds:(NSArray<NSString *> *)channelIds
                          keyword:(NSString *)keyword
                        startTime:(long long)startTime
                            limit:(int)limit
                          success:(void (^)(NSArray<RCMessage *> *messages))successBlock
                            error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Use ConversationType_ULTRAGROUP for ultra group conversations.
targetId	NSString	Ultra group targetId.
channelIds	NSArray	Array of ultra group channel IDs. Cannot be empty. Maximum 50 channels. All channel IDs must be valid (alphanumeric characters). Empty strings are not supported.
keyword	NSString	Search keyword. Pass empty string to search all matching messages.
startTime	long long	Start timestamp for search. Pass 0 to search from latest messages. Non-zero values search backwards from this timestamp.
limit	int	Number of search results to return. Must be > 0. Maximum is 100. Values exceeding 100 will default to 100.
successBlock	Block	Success callback. Returns matched RCMessage list in messages.
errorBlock	Block	Failure callback. Returns corresponding error code.

Sample Code

[[RCChannelClient sharedChannelManager] searchMessagesForChannels:ConversationType_ULTRAGROUP
                 targetId:@"ultra group targetId"
               channelIds:@[@"ultra group channel ID"]
                  keyword:searchText
                startTime:startTime
                    limit:100
                  success:^(NSArray<RCMessage *> * _Nonnull messages) {

                  } error:^(RCErrorCode status) {

}];

Search Local Messages Across Multiple Channels in an Ultra Group by Sender User ID

tip

Available since SDK v5.6.2.

Interface Prototype

- (void)searchMessagesByUserForChannels:(RCConversationType)conversationType
                               targetId:(NSString *)targetId
                             channelIds:(NSArray<NSString *> *)channelIds
                                 userId:(NSString *)userId
                              startTime:(long long)startTime
                                  limit:(int)limit
                                success:(void (^)(NSArray<RCMessage *> *messages))successBlock
                                  error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. Use ConversationType_ULTRAGROUP for ultra group conversations.
targetId	NSString	Ultra group targetId.
channelIds	NSArray	Array of ultra group channel IDs. Cannot be empty. Maximum 50 channels. All channel IDs must be valid (alphanumeric characters). Empty strings are not supported.
userId	NSString	Target user ID for search.
startTime	long long	Start timestamp for search. Pass 0 to search from latest messages. Non-zero values search backwards from this timestamp.
limit	int	Number of search results to return. Must be > 0. Maximum is 100. Values exceeding 100 will default to 100.
successBlock	Block	Success callback. Returns matched RCMessage list in messages.
errorBlock	Block	Failure callback. Returns corresponding error code.

Sample Code

[[RCChannelClient sharedChannelManager] searchMessagesForChannels:ConversationType_ULTRAGROUP
                 targetId:@"ultra group targetId"
               channelIds:@[@"ultra group channel ID"]
                   userId:@"userId"
                startTime:startTime
                    limit:100
                  success:^(NSArray<RCMessage *> * _Nonnull messages) {

                  } error:^(RCErrorCode status) {

}];

[[RCChannelClient sharedChannelManager] searchMessagesForChannels:ConversationType_ULTRAGROUP
                 targetId:@"ultra group targetId"
               channelIds:@[@"ultra group channel ID"]
                   userId:@"userId"
                startTime:startTime
                    limit:100
                  success:^(NSArray<RCMessage *> * _Nonnull messages) {

                  } error:^(RCErrorCode status) {

}];

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

tip

This method has been available since SDK version 5.6.2.

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

Interface Prototype

- (void)searchMessagesByUserForAllChannel:(RCConversationType)conversationType
                                 targetId:(NSString *)targetId
                                   userId:(NSString *)userId
                                startTime:(long long)startTime
                                    limit:(int)limit
                                  success:(void (^)(NSArray<RCMessage *> *messages))successBlock
                                    error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
conversationType	RCConversationType	Conversation type. For ultra group conversations, pass ConversationType_ULTRAGROUP.
targetId	NSString	Ultra group targetId.
userId	NSString	The userId of the user to search for.
startTime	long long	The starting time for querying records. Pass 0 to start searching from the latest message. Pass a non-zero value to search backward from that time.
limit	int	The number of search results to return. The limit must be greater than 0. The maximum is 100. If the limit exceeds 100, 100 messages are returned by default.
successBlock	Block	Callback for successful search. messages returns the matched RCMessage list.
errorBlock	Block	Callback for failed search, returning the corresponding error code.

Example Code

[[RCChannelClient sharedChannelManager] searchMessagesByUserForAllChannel:ConversationType_ULTRAGROUP
                         targetId:@"ultra group targetId"
                           userId:@"userId"
                        startTime:startTime
                            limit:100
                          success:^(NSArray<RCMessage *> * _Nonnull messages) {

                          } error:^(RCErrorCode status) {

}];