SDKsFlutter

Search messages

Search locally synchronized messages by keyword and conversation criteria with the Flutter SDK.

Search through the locally synchronized message database on the current client by keywords, conversation, message types, and time ranges. When searching within a group chat, supply the corresponding conversationID rather than the groupID used during message sending.

If you only hold a target user ID or group ID, first call Generate conversation ID to obtain the conversation ID. To perform a global search across all local conversations, pass null for conversationID.

The search scope is limited to messages already synchronized to the SDK's local database. Global full-text search across cloud history is an enterprise server capability; a backend search service can return matching conversation and message IDs for client navigation.

Basic keyword search

The keywordList parameter accepts a list of strings, but the search engine currently matches against the first non-empty keyword. Trim whitespace and filter empty values before submitting:

final keyword = input.trim();
if (keyword.isNotEmpty) {
  final result = await OpenIM.iMManager.messageManager.searchLocalMessages(
    conversationID: conversationID,
    keywordList: [keyword],
    messageTypeList: [MessageType.text, MessageType.atText],
    pageIndex: 1,
    count: 20,
  );
  renderSearchResult(result);
}

Advanced filtered search

The search API also supports compound filtering by message type and time window:

final result = await OpenIM.iMManager.messageManager.searchLocalMessages(
  conversationID: conversationID,
  keywordList: ['release'],
  messageTypeList: [MessageType.text],
  searchTimePosition: searchTimePosition,
  searchTimePeriod: searchTimePeriod,
  pageIndex: 1,
  count: 20,
);

To include images, files, or custom messages in the search, add their corresponding MessageType integer constants to messageTypeList. Passing an empty list removes message type restrictions.

Parameters

Parameter	Type	Required	Description
`conversationID`	`String?`	No	ID of the specific conversation to search. Pass `null` to search across all local conversations.
`keywordList`	`List<String>`	No	List of search keywords. The current implementation matches against the first non-empty keyword.
`keywordListMatchType`	`int`	No	Matching strategy for multiple keywords; defaults to `0`.
`senderUserIDList`	`List<String>`	No	Sender filter list; defaults to an empty list.
`messageTypeList`	`List<int>`	No	Filter list of `MessageType` integer constants (such as `MessageType.text`). An empty list matches all types.
`searchTimePosition`	`int`	No	Search start timestamp in seconds; defaults to `0` (starts from the current time).
`searchTimePeriod`	`int`	No	Number of seconds to search backward from `searchTimePosition`; defaults to `0` (unlimited).
`pageIndex`	`int`	No	One-based page number; defaults to `1`.
`count`	`int`	No	Number of matching items per page; defaults to `40`.

Return value

Returns a Future resolving to a search result object (SearchResult). All fields may be nullable:

Field	Type	Description
`totalCount`	`int?`	Total number of messages matching the search criteria.
`searchResultItems`	`List<SearchResultItems>?`	Search results grouped by conversation.
`findResultItems`	`List<SearchResultItems>?`	Exact-match items; this method primarily populates `searchResultItems`.

Each SearchResultItems item aggregates matching messages for one conversation:

Field	Type	Description
`conversationID`	`String?`	ID of the conversation containing matched messages.
`conversationType`	`int?`	Conversation type.
`showName`	`String?`	Display name of the conversation.
`faceURL`	`String?`	Avatar URL of the conversation.
`messageCount`	`int?`	Total number of matched messages in this conversation.
`messageList`	`List<Message>?`	Matched messages retrieved for the current page.

When paginating through results, keep all search filters identical and increment only pageIndex. When search keywords or filters change, clear previous results and reset pageIndex to 1. Deduplicate search items using conversationID and non-empty clientMsgID values.

State changes after the call

Local search queries retrieve a static snapshot of database records and do not trigger event callbacks.

Messages matching search results may subsequently be revoked, deleted, or supplemented by background sync while the search view is open. Update result states using the centralized listeners described in Receive messages, Delete saved messages, and Revoke a message. Avoid registering redundant message listeners in search components.

To navigate to a matched message in chat, use the item's conversationID and clientMsgID. To load surrounding conversation context, follow Locate messages by ID to fetch older and newer records.

Was this page helpful?

Basic keyword search

Advanced filtered search

Parameters

Return value

State changes after the call

Related guides