SDKsiOS

Search messages

Search messages already synchronized to the iOS SDK’s local storage.

Invoke searchLocalMessages:onSuccess:onFailure: on OIMManager to search for messages containing specified keywords across history synchronized to the local database. When searching group chat messages, provide the group's corresponding conversationID rather than groupID:

Parameters

Parameter	Type	Required	Description
`param`	`OIMSearchParam *`	Yes	Search criteria parameters object.

Properties of OIMSearchParam

Parameter	Type	Required	Description
`conversationID`	`NSString *`	No	Target conversation ID. Pass an empty string `@""` to search across all local conversations. For group chats, pass the conversation ID rather than `groupID`.
`keywordList`	`NSArray<NSString > `	Yes	Array of keyword strings. Currently supports a single keyword.
`keywordListMatchType`	`NSInteger`	No	Multi-keyword matching mode (currently reserved).
`senderUserIDList`	`NSArray * _Nullable`	No	Sender user ID filter list (currently reserved).
`messageTypeList`	`NSArray * _Nullable`	No	Optional array of message content type codes (such as text messages).
`searchTimePosition`	`NSInteger`	No	Starting UTC timestamp in seconds. Pass `0` to search from current time.
`searchTimePeriod`	`NSInteger`	No	Time window in seconds from the starting point. Pass `0` for unrestricted range.
`pageIndex`	`NSInteger`	Yes	Page index starting from `1` for single-conversation searches. Ignored during cross-conversation searches.
`count`	`NSInteger`	Yes	Number of messages per page for single-conversation searches. Ignored during cross-conversation searches.

Code example

NSString *keyword = [searchText stringByTrimmingCharactersInSet:
    NSCharacterSet.whitespaceAndNewlineCharacterSet];
if (keyword.length == 0) {
    [self renderSearchItems:@[] totalCount:0];
    return;
}

OIMSearchParam *param = [OIMSearchParam new];
param.conversationID = conversationID;
param.keywordList = @[keyword];
param.messageTypeList = @[@(OIMMessageContentTypeText)];
param.searchTimePosition = 0;
param.searchTimePeriod = 0;
param.pageIndex = 1;
param.count = 20;

[[OIMManager manager] searchLocalMessages:param
    onSuccess:^(OIMSearchResultInfo * _Nullable result) {
        if (result == nil) {
            [self showSearchError:0 message:@"Search callback returned no result"];
            return;
        }
        [self renderSearchItems:result.searchResultItems
                     totalCount:result.totalCount];
    }
    onFailure:^(NSInteger code, NSString * _Nullable message) {
        [self showSearchError:code message:message ?: @"Search failed"];
    }];

Return value

The onSuccess callback delivers an OIMSearchResultInfo model containing:

Property	Type	Description
`totalCount`	`NSInteger`	Total number of messages matching search criteria.
`searchResultItems`	`NSArray<OIMSearchResultItemInfo > `	Array of search result buckets grouped by conversation.
`findResultItems`	`NSArray<OIMSearchResultItemInfo > `	Result items dedicated to exact ID lookup; not the primary search list.

Each OIMSearchResultItemInfo conversation bucket contains:

Property	Type	Description
`conversationID`	`NSString *`	Identifier of the conversation containing matches.
`conversationType`	`OIMConversationType`	Conversation type enum.
`showName`	`NSString *`	Conversation display name.
`faceURL`	`NSString *`	Conversation avatar URL.
`messageCount`	`NSInteger`	Number of matching messages in this conversation.
`messageList`	`NSArray<OIMMessageInfo > `	Array of matching messages on the current page for this conversation.

State changes after the call

Local cache reading: Search executes against the local SQLite database snapshot only and does not trigger real-time message listeners.
Pagination and deduplication: When paging through single-conversation matches, keep query parameters identical and increment pageIndex. Deduplicate items using composite key conversationID:clientMsgID.
Context navigation: When a user selects a search result item, obtain the full message model via Find messages by ID if needed, and retrieve adjacent messages via Load message context.

Was this page helpful?