全文搜索消息 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

全文搜索消息

更新时间： 2025/07/11 11:36:03

网易云信 IM 支持对 客户端本地 和 网易云信服务器 存储的历史消息进行检索，提供精准、高效的搜索体验，帮助用户快速定位至目标信息。

本文介绍如何调用 NIM SDK 的接口实现历史消息的搜索。

支持平台

本文内容适用的开发平台或框架如下表所示，涉及的接口请参考下文相关接口章节：

安卓	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	鸿蒙	Flutter
✔️️️️️	✔️️️️️	✔️️️️️	✔️️️️️	✔️️️️️	✔️️️️️	✔️️️️️

前提条件

若需要使用云端历史消息全文搜索功能，需要提前在网易云信控制台开通 全文云端消息检索 功能，具体请参考配置基础功能/全局功能。

云端历史消息的存储时长在不同的套餐包中不同，各套餐包中的限制具体请参考增值服务。

全文搜索云端历史消息

调用 searchCloudMessagesEx 或 searchCloudMessages 方法，对指定会话、对象的云端历史消息进行全局关键字内容搜索。

暂不支持搜索超大群历史消息。

Android

JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);

// 创建搜索参数
V2NIMMessageSearchExParams searchParams = V2NIMMessageSearchExParams.V2NIMMessageSearchExParamsBuilder
        // 设置会话ID
        .builder("conversationId")
        // 设置关键词列表
        .withKeywordList(Arrays.asList("关键词1", "关键词2"))
        // 设置关键词匹配类型
        .withKeywordMatchType(V2NIMSearchKeywordMathType.V2NIM_SEARCH_KEYWORD_MATH_TYPE_OR)
        // 设置发送者账号列表
        .withSenderAccountIds(Arrays.asList("发送者ID1", "发送者ID2"))
        // 设置消息类型
        .withMessageTypes(Arrays.asList(V2NIMMessageType.V2NIM_MESSAGE_TYPE_TEXT, V2NIMMessageType.V2NIM_MESSAGE_TYPE_IMAGE))
        // 设置搜索开始时间(毫秒时间戳)
        .withSearchStartTime(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000)
        // 设置搜索时间跨度(毫秒)
        .withSearchTimePeriod(7 * 24 * 60 * 60 * 1000)
        // 设置分页大小限制
        .withLimit(20)
        // 设置分页标记(首次搜索传空)
        .withPageToken("")
        // 设置消息子类型
        .withMessageSubtypes(Arrays.asList(1, 2))
        .build();

v2MessageService.searchCloudMessagesEx(searchParams,
        new V2NIMSuccessCallback<V2NIMMessageSearchResult>() {
            @Override
            public void onSuccess(V2NIMMessageSearchResult result) {
                // 获取搜索到的消息列表
                List<V2NIMMessage> messages = result.getMessages();
                // 获取下一页的分页标记
                String nextPageToken = result.getNextPageToken();
                
                // 处理搜索结果...
                for (V2NIMMessage message : messages) {
                    // 处理每条消息
                }
                
                // 如果需要加载下一页
                if (nextPageToken != null && !nextPageToken.isEmpty()) {
                    // 使用nextPageToken继续加载下一页
                }
            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {
                // 处理错误
                int code = error.getCode();
                String message = error.getMessage();
                // 处理搜索失败...
            }
        });

iOS

Objective-CV2NIMMessageSearchExParams *params = [[V2NIMMessageSearchExParams alloc] init];
// 按需设置搜索参数
// params.conversationId = conversationId;
// params.keywordList = keywordList;
// params.keywordMatchType = keywordMatchType;
// params.senderAccountIds = senderAccountIds;
// params.messageTypes = messageTypes;
// params.searchStartTime = searchStartTime;
// params.searchTimePeriod = searchTimePeriod;
// params.limit = limit;

[[NIMSDK sharedSDK].v2MessageService searchCloudMessagesEx:params success:^(V2NIMMessageSearchResult * _Nonnull result) {
    // 如果需要翻页查询，从 V2NIMMessageSearchResult 获取 nextPageToken，用于下一页查询
    NSString *pageToken = result.nextPageToken;
    // 处理搜索结果
} failure:^(V2NIMError * _Nonnull error) {

}];

macOS/Windows

C++V2NIMMessageSearchExParams params;
nstd::vector<nstd::string> keywordList;
keywordList.push_back("keyword");
params.keywordList = keywordList;
params.messageLimit = 20;
messageService.searchCloudMessagesEx(
    params,
    [](nstd::vector<V2NIMMessage> messages) {
        for (auto&& message : messages) {
            // do something
        }
    },
    [](V2NIMError error) {
        // search cloud messages failed, handle error
    });

Web/uni-app/小程序

TypeScripttry {
const res: V2NIMMessageSearchResult = await nim.V2NIMMessageService.searchCloudMessagesEx({
    conversationId: 'cjl|1|cjl1',
    keywordList: ['周', '杰', '伦'],
    keywordMatchType: undefined,
    senderAccountIds: ['cjl1', 'cjl2'],
    messageTypes: [],
    searchStartTime: 1234567890, // timestamp
    searchTimePeriod: 7 * 24 * 60 * 60 * 1000, // 7 day
    limit: 1,
    pageToken: undefined
});
// todo: Success
} catch (err) {
// todo: error
}

Node.js/Electron

TypeScriptconst result = await v2.messageService.searchCloudMessagesEx({
   keywordList: ['keyword1', 'keyword2'],
   messageTypes: [0, 1, 2],
   messageSubtypes: [1, 2],
   limit: 10
})

HarmonyOS

TypeScriptconst params: V2NIMMessageSearchExParams = {
  conversationId: 'cjl|1|cjl1',
  keywordList: ['周', '杰', '伦'],
  keywordMatchType: undefined,
  senderAccountIds: ['cjl1', 'cjl2'],
  messageTypes: [],
  searchStartTime: 1234567890, // timestamp
  searchTimePeriod: 7 * 24 * 60 * 60 * 1000, // 7 day
  limit: 1,
  pageToken: undefined
}
const messageResult: V2NIMMessageSearchResult = await nim.messageService.searchCloudMessagesEx(params)

Flutter

Dart// 创建搜索参数
final params = NIMMessageSearchExParams(
  conversationId: 'cjl|1|cjl1',
  keywordList: ['周', '杰', '伦'],
);

// 执行云端消息搜索
NimCore.instance.messageService
    .searchCloudMessagesEx(params)
    .then((result) {
  if (result.isSuccess && result.data != null) {
    // 搜索成功
    final searchResult = result.data!;
    print('searchCloudMessages result: ${searchResult.toJson()}');
    print('count: ${searchResult.count}');
    print('hasMore: ${searchResult.hasMore}');
    print('nextPageToken: ${searchResult.nextPageToken}');

    // 处理搜索到的消息
    searchResult.items?.forEach((e) {
      //会话 id
      print('conversationId: ${e.conversationId}');
      //单个会话的返回数量
      print('count: ${e.count}');
      e.messages?.forEach((message) {
        print('message: ${message.toJson()}');
      });
    });
  } else {
    // 搜索失败
    print('searchCloudMessages failed: ${result.code}, ${result.errorDetails}');
  }
});

全文搜索本地历史消息

调用 searchLocalMessages 方法，可以对指定会话、对象的本地历史消息进行全局关键字内容搜索。

Android、iOS 以及鸿蒙平台下，若需要使用本地搜索功能，需要在集成 SDK 时单独引入 检索库。具体请参考集成 SDK 文档（Android | iOS | 鸿蒙）。

安卓

Java//        String conversationId;
//        List<String> keywordList;
//        V2NIMSearchKeywordMathType keywordMatchType;
//        List<String> senderAccountIds;
//        List<V2NIMMessageType> messageTypes;
//        long searchStartTime;
//        long searchTimePeriod;
//        int limit;
        V2NIMMessageSearchExParams params = V2NIMMessageSearchExParams.V2NIMMessageSearchExParamsBuilder.builder()
        // 按需设置搜索参数
//        .withConversationId(conversationId)
//        .withKeywordList(keywordList)
//        .withMessageTypes(keywordMatchType)
//        .withSenderAccountIds(senderAccountIds)
//        .withMessageTypes(messageTypes)
//        .withSearchStartTime(searchStartTime)
//        .withSearchTimePeriod(searchTimePeriod)
//        .withLimit(limit)
        .build();

        NIMClient.getService(V2NIMMessageService.class).searchLocalMessages(params, new V2NIMSuccessCallback<V2NIMMessageSearchResult>() {
            @Override
            public void onSuccess(V2NIMMessageSearchResult v2NIMMessageSearchResult) {
                // 如果需要翻页查询，从 V2NIMMessageSearchResult 获取 nextPageToken，用于下一页查询
                String pageToken = v2NIMMessageSearchResult.getNextPageToken();
            }
        }, new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {

            }
        });

iOS

Objective-CV2NIMMessageSearchExParams *params = [[V2NIMMessageSearchExParams alloc] init];
// 按需设置搜索参数
// params.conversationId = conversationId;
// params.keywordList = keywordList;
// params.keywordMatchType = keywordMatchType;
// params.senderAccountIds = senderAccountIds;
// params.messageTypes = messageTypes;
// params.searchStartTime = searchStartTime;
// params.searchTimePeriod = searchTimePeriod;
// params.limit = limit;

[[NIMSDK sharedSDK].v2MessageService searchLocalMessages:params success:^(V2NIMMessageSearchResult * _Nonnull result) {
        // 如果需要翻页查询，从 V2NIMMessageSearchResult 获取 nextPageToken，用于下一页查询
        NSString *pageToken = result.nextPageToken;
        // 处理搜索结果
    } failure:^(V2NIMError * _Nonnull error) {

    }];

macOS/Windows

C++V2NIMMessageSearchExParams params;
nstd::vector<nstd::string> keyword_list;
keywordList.push_back("keyword");
params.keywordList = keyword_list;
params.limit = 20;
messageService.searchLocalMessages(
    params,
    [](const V2NIMMessageSearchResult& result) {
        for (auto&& message : result.items) {
            // do something
        }
    },
    [](const V2NIMError& error) {
        // search local messages failed, handle error
    });

Web/uni-app/小程序

因平台属性，暂不支持。

Node.js/Electron

TypeScriptconst result = await v2.messageService.searchLocalMessages({
   keywordList: ['keyword1', 'keyword2'],
})

鸿蒙

TypeScriptconst params: V2NIMMessageSearchExParams = {
  conversationId: 'cjl|1|cjl1',
  keywordList: ['周', '杰', '伦'],
  keywordMatchType: undefined,
  senderAccountIds: ['cjl1', 'cjl2'],
  messageTypes: [],
  searchStartTime: 1234567890, // timestamp
  searchTimePeriod: 7 * 24 * 60 * 60 * 1000, // 7 day
  limit: 1,
  pageToken: undefined
}
const messageResult: V2NIMMessageSearchResult = await nim.messageService.searchLocalMessages(params)

Flutter

Dart// 创建搜索参数
final params = NIMMessageSearchExParams(
  conversationId: 'cjl|1|cjl1',
  keywordList: ['周', '杰', '伦'],
);

// 执行本地消息搜索
NimCore.instance.messageService
    .searchLocalMessages(params)
    .then((result) {
  if (result.isSuccess && result.data != null) {
    // 搜索成功
    final searchResult = result.data!;
    print('searchLocalMessages result: ${searchResult.toJson()}');
    print('count: ${searchResult.count}');
    print('hasMore: ${searchResult.hasMore}');
    print('nextPageToken: ${searchResult.nextPageToken}');

    // 处理搜索到的消息
    searchResult.items?.forEach((e) {
      //会话 id
      print('conversationId: ${e.conversationId}');
      //单个会话的返回数量
      print('count: ${e.count}');
      e.messages?.forEach((message) {
        print('message: ${message.toJson()}');
      });
    });
  } else {
    // 搜索失败
    print('searchLocalMessages failed: ${result.code}, ${result.errorDetails}');
  }
});

API	说明
`searchCloudMessages`	全文搜索云端历史消息
`searchCloudMessagesEx`	全文搜索云端历史消息注：较 `searchCloudMessages` 方法，入参支持传入多个 keyword
`searchLocalMessages`	全文搜索本地历史消息（除 Web 端）