Search messages

searchLocalMessages() searches messages already synchronized into the current user's local database. For a group, pass the group's conversationID, not the groupID used when sending. If you only have the group ID, first obtain the conversation ID with Get a conversation ID.

Use a backend search service for cross-user audit, complete server-side history, complex permission filtering, or global ranking. It can return conversationID and clientMsgID so the client can locate each hit.

Create a search query

keywordList accepts one or more terms. A normal search box represents one input, so trim it and reject empty values before calling the SDK.

import {
  OpenIMMessageTypeAtText,
  OpenIMMessageTypeText,
  searchLocalMessages,
  type OpenIMMessageItem,
  type OpenIMSearchMessageResult,
} from '@/uni_modules/unix-openim-sdk'

const result = await searchLocalMessages({
  conversationID,
  keywordList: [keyword.trim()],
  keywordListMatchType: 0,
  senderUserIDList: [],
  messageTypeList: [OpenIMMessageTypeText, OpenIMMessageTypeAtText],
  searchTimePosition: 0,
  searchTimePeriod: 0,
  pageIndex: 1,
  count: 20,
})

Advanced search

Narrow the query by sender, content type, and time window. In OpenIMSearchLocalMessagesParams, every filter and paging field except conversationID is required. Use an empty array for an unrestricted list and the server-defined 0 values when time is unrestricted.

const result = await searchLocalMessages({
  conversationID,
  keywordList: ['release'],
  keywordListMatchType: 0,
  senderUserIDList: [senderUserID],
  messageTypeList: [OpenIMMessageTypeText],
  searchTimePosition,
  searchTimePeriod,
  pageIndex: 1,
  count: 20,
})

Parameters

Add the appropriate OpenIMMessageType constants when the UI searches images, files, or custom messages. Matching modes, time units, and page numbering must follow the SDK and server contract.

Handle paginated results

The Promise resolves to OpenIMSearchMessageResult | null:

Each result item contains:

Preserve both the conversation ID and message ID when flattening grouped results:

type SearchMessageRow = {
  conversationID : string
  clientMsgID : string
  message : OpenIMMessageItem
}

function toSearchRows(result : OpenIMSearchMessageResult) : Array<SearchMessageRow> {
  const rows : Array<SearchMessageRow> = []
  result.searchResultItems.forEach((item) => {
    item.messageList.forEach((message) => {
      const clientMsgID = message.clientMsgID
      if (clientMsgID != null) {
        rows.push({ conversationID: item.conversationID, clientMsgID, message })
      }
    })
  })
  return rows
}

Keep all filters unchanged while incrementing pageIndex. When any condition changes, reset the page to 1 and clear old rows. Deduplicate by conversationID:clientMsgID; do not persist selection by array position. A search does not emit message events.

Handle changes to search results

A hit can be revoked or deleted while the search page is open, and newly synchronized messages can change the result set. Use the shared handlers described in Receive messages, Delete saved messages, and Revoke a message. This page owns querying and pagination, not duplicate event registrations.

Navigate with the result's conversationID and clientMsgID. To display nearby chat records, use the complete hit as the start point for Load message context, rather than assembling context with findMessageList().

Re-run the current page query when the UI needs a fresh snapshot. Search Promises, event increments, and reconciliation queries are independent. Clear previous-account search state after login changes.

Related pages

• Find messages by ID
• Load older messages
• Receive messages