Locate messages by ID

When navigating to a chat screen from search results, quoted replies, or system notifications, retrieve locally synchronized message records using conversationID and clientMsgID:

Parameters

Code example

final result = await OpenIM.iMManager.messageManager.findMessageList(
  searchParams: [
    SearchParams(
      conversationID: conversationID,
      clientMsgIDList: [clientMsgID],
    ),
  ],
);

final items = result.findResultItems ?? const <SearchResultItems>[];
final messages = items.isEmpty
    ? const <Message>[]
    : (items.first.messageList ?? const <Message>[]);
final target = messages.isEmpty ? null : messages.first;

Upon Future completion, matched messages are located in the messageList of SearchResult.findResultItems. If records have not synchronized locally, were deleted, or the IDs do not exist, the list may be empty; verify elements before accessing.

clientMsgID is the stable primary key managed on the client side. Sending, receiving, searching, and history retrieval must all use it as the merge key, rather than list indices or display timestamps.

Load surrounding messages

After locating the target message, if you need to restore full conversation context before and after it, use the target message as a cursor. Call Load older message history to fetch earlier messages, and call Load newer message history Enterprise to fetch later messages, assembling the full context using conversationID:clientMsgID:

final older = await OpenIM.iMManager.messageManager
    .getAdvancedHistoryMessageList(
      conversationID: conversationID,
      startMsg: target,
      count: 20,
    );
final newer = await OpenIM.iMManager.messageManager
    .getAdvancedHistoryMessageListReverse(
      conversationID: conversationID,
      startMsg: target,
      count: 20,
    );

When combining older messages, the target, and newer messages, discard nullable or empty clientMsgID values and deduplicate strictly by conversationID:clientMsgID. Never rely on array indices to identify the target message.

Locate requests can return empty results if local storage is not yet synchronized, or if the message was deleted or revoked. Retry the query after synchronization completes. Revocation and deletion updates are handled by global message listeners.

Retrieve the latest group message

If you only need to display the latest message in a group (for example, in a chat list preview or group entry tile), retrieve the corresponding ConversationInfo:

final conversation = await OpenIM.iMManager.conversationManager
    .getOneConversation(
  sourceID: groupID,
  sessionType: ConversationType.superGroup,
);

renderConversationPreview(
  conversationID: conversation.conversationID,
  latestMessage: conversation.latestMsg,
  unreadCount: conversation.unreadCount,
);

ConversationInfo.latestMsg is a nullable Message and does not require manual JSON parsing. When opening its surrounding context, verify that latestMsg and its clientMsgID are valid, then use the current conversationID to load messages in both directions.

Return value

Message queries, surrounding history pagination, and conversation lookups are read-only operations. Future completion returns point-in-time data snapshots and does not trigger event callbacks.

The UI can render the returned results directly. Subsequent new arrivals, revocations, and deletions must be handled through global listeners, merging updates idempotently using the composite key conversationID:clientMsgID.

Related guides

• Load older message history
• Load newer message history
• Search messages
• Receive messages