文档概览/

Unity

搜索云端消息

功能描述

消息云端搜索是提升 App 使用体验的必备功能。它能帮助用户从海量信息中快速找到目标内容，操作简单便捷；同时也可作为运营工具，高效引导用户浏览相关内容，提升使用效率。
说明：
消息云端搜索功能仅 7.9.5666 及以上版本支持，最大支持搜索近360天内的消息数据，与历史消息存储时间保持一致。
云端搜索功能仅对专业版 Plus 和企业版客户开放，购买专业版 Plus 和企业版 后可使用；体验版支持一定额度免费试用，有效期一个月。
如果您没有开通该服务，调用接口会返回 60020 错误码。

消息搜索类介绍

消息搜索参数类

消息搜索参数类为 MessageSearchParam。搜索消息时，SDK 会按照该对象的设置，执行不同的搜索逻辑。
MessageSearchParam 的参数说明如下：
参数
含义
说明
msg_search_param_keyword_array
关键字列表
最多支持 5 个。当消息发送者以及消息类型均未指定时，必须设置关键字列表；否则，关键字列表可以为空。
msg_search_param_keyword_list_match_type
指定关键字列表匹配类型
可设置为 “或” 关系搜索，或 “与” 关系搜索。取值分别为 TIMKeywordListMatchType_Or 和 TIMKeywordListMatchType_And。默认为 “或” 关系搜索。
msg_search_param_send_identifier_array
指定 userID 发送的消息
最多支持 5 个。
msg_search_param_message_type_array
指定搜索的消息类型集合
传空表示搜索支持的全部类型消息（kTIMElem_Face 和 kTIMElem_GroupTips 不支持搜索）。其他类型取值参考 TIMElemType。
msg_search_param_conv_id
搜索 “全部会话” 还是搜索 “指定的会话”
msg_search_param_conv_id 为空，搜索全部会话；msg_search_param_conv_id 不为空，搜索指定会话。
msg_search_param_search_time_position
搜索的起始时间点
默认为 0（从现在开始搜索）。UTC 时间戳，单位：秒。
msg_search_param_search_time_period
从起始时间点开始的过去时间范围
默认为 0（不限制时间范围）。24 x 60 x 60 代表过去一天，单位：秒。
msg_search_param_search_count
搜索的数量
搜索的数量，最大支持100。
msg_search_param_search_cursor
搜索的游标
搜索的起始位置，第一次填写空字符串，续拉时填写上一次返回的 MessageSearchResult 中的 msg_search_result_search_cursor。

消息搜索结果类

消息搜索结果类为 MessageSearchResult。参数说明如下：
参数
含义
说明
msg_search_result_total_count
搜索结果总数
如果搜索指定会话，返回满足搜索条件的消息总数。
如果搜索全部会话，返回满足搜索条件的消息所在的所有会话总数量。
msg_search_result_item_array
搜索结果列表
如果搜索指定会话，返回结果列表只包含该会话结果。
如果搜索全部会话，会对满足搜索条件的消息根据会话 ID 分组，分页返回分组结果。
msg_search_result_search_cursor
续拉的游标
调用搜索接口续拉时需要填的游标
其中 msg_search_result_item_array 是个列表，内含 MessageSearchResultItem对象，参数说明如下：
参数
含义
说明
msg_search_result_item_conv_id
会话 ID
-
msg_search_result_item_total_message_count
消息数量
当前会话一共搜索到了多少条符合要求的消息。
msg_search_result_item_message_array
满足搜索条件的消息列表
如果搜索指定会话，msg_search_result_item_message_array 中装载的是本会话中所有满足搜索条件的消息列表。
如果搜索全部会话，msg_search_result_item_message_array 中装载的消息条数会有如下两种可能：
如果某个会话中匹配到的消息条数 > 1，则 msg_search_result_item_message_array 为空，您可以在 UI 上显示 “{msg_search_result_item_total_message_count} 条相关记录”。
如果某个会话中匹配到的消息条数 = 1，则 msg_search_result_item_message_array 为匹配到的那条消息，您可以在 UI 上显示之，并高亮匹配关键词。

搜索全部会话的消息

当用户在搜索框输入关键字搜索消息时，您可以调用 MsgSearchCloudMessages 搜索消息。
如果您希望在全部会话范围内搜索，只需要将 MessageSearchParam 中的 msg_search_param_conv_id 设置为空或者不设置即可。
示例代码如下：
List<string> keywordList = new List<string>();
keywordList.add("abc");
keywordList.add("123");
MessageSearchParam searchParam = new MessageSearchParam
{
  msg_search_param_keyword_array = keywordList,
  msg_search_param_conv_id = "",
  msg_search_param_search_count = 20,
  msg_search_param_search_time_position = 0,
  msg_search_param_search_time_period = 600,
  msg_search_param_search_cursor = ""
};

TencentIMSDK.MsgSearchCloudMessages(searchParam, (int code, string desc, MessageSearchResult result, string user_data)=>{
 // 处理异步逻辑
});

搜索指定会话的消息

当用户在搜索框输入关键字搜索消息时，您可以调用 MsgSearchCloudMessages 搜索消息。
示例代码如下：
List<string> keywordList = new List<string>();
keywordList.add("abc");
keywordList.add("123");
MessageSearchParam searchParam = new MessageSearchParam
{
  msg_search_param_keyword_array = keywordList,
  msg_search_param_conv_id = "c2c_user1",
  msg_search_param_search_count = 20,
  msg_search_param_search_time_position = 0,
  msg_search_param_search_time_period = 600,
  msg_search_param_search_cursor = ""
};

TencentIMSDK.MsgSearchCloudMessages(searchParam, (int code, string desc, MessageSearchResult result, string user_data)=>{
 // 处理异步逻辑
});

搜索典型场景示例

普通的 IM 聊天软件，搜索界面的展示通常分这几种场景：
图 1：搜索聊天记录
图 2：搜索更多聊天记录
图 3：搜索指定会话的消息






下文我们将依次向您展示如何利用 IM SDK 的搜索 API 实现上图的典型场景。

展示最近几个活跃的会话

如图 1 所示，最下方是搜索到的消息所属的最近 3 个会话列表，实现方式如下：
1. 设置搜索参数 MessageSearchParam
msg_search_param_conv_id 设置为 null 或者 ""，表示搜索所有会话的消息。
msg_search_param_search_cursor 设置为 ""，表示搜索最新的数据。
msg_search_param_search_count 设置为 3，表示返回最近的会话数量，UI 上一般显示 3 条。
2. 处理搜索回调结果MessageSearchResult
msg_search_result_total_count 表示匹配到的消息所属的所有会话数量。
msg_search_result_item_array 列表为最近 3（即入参 msg_search_param_search_count）个会话信息。其中元素MessageSearchResultItem 的 msg_search_result_item_total_message_count 表示当前会话搜索到的消息总数量：
搜索到的消息条数 > 1，则 msg_search_result_item_array 为空，您可以在 UI 上显示 “4 条相关聊天记录”，其中的 4 为 msg_search_result_total_count。
搜索到的消息条数 = 1，则 msg_search_result_item_array 为匹配到的那条消息，您可以在 UI 上显示消息内容并高亮搜索关键词，例如搜索典型场景示例图中的 “test”。
示例代码如下：
List<string> keywordList = new List<string>();
keywordList.add("test");
MessageSearchParam searchParam = new MessageSearchParam
{
  msg_search_param_keyword_array = keywordList,
  msg_search_param_conv_id = "",
  msg_search_param_search_count = 3,
  msg_search_param_search_cursor = ""
};

TencentIMSDK.MsgSearchCloudMessages(searchParam, (int code, string desc, MessageSearchResult result, string user_data)=>{
    // 匹配到的消息所属的所有会话数量
    int totalCount = result.msg_search_result_total_count;
    // 最近3个根据消息会话分类的信息
    List<MessageSearchResultItem> resultItemList = result.msg_search_result_item_array;
    foreach (var resultItem in resultItemList) {
        // 会话 ID
        string conversationID = resultItem.msg_search_result_item_conv_id;
        // 该会话匹配到的所有消息数量
        int totalMessageCount = resultItem.msg_search_result_item_total_message_count;
        // 消息列表：如果 totalMessageCount > 1，该列表为空；如果 totalMessageCount = 1，该列表元素为此消息
        List<Message> messageList = resultItem.msg_search_result_item_message_array;
    }
});

展示所有搜索到的消息所属会话列表

单击 搜索典型场景示例 图 1 中的 “更多聊天记录”，会跳转到图 2，展示所有搜索到的消息所属的会话列表。搜索参数和搜索结果描述跟上文的场景类似。
为了防止内存膨胀，我们强烈建议您分页加载会话列表。
举个例子，分页加载，每页展示 10 条会话结果，搜索参数MessageSearchParam 可以参考如下设置：
1. 首次调用：设置参数 msg_search_param_search_count = 10，msg_search_param_search_cursor = ""。调用 MsgSearchCloudMessages 获取消息搜索结果，解析并展示到首页，并且从结果回调中获取会话总数量 msg_search_result_total_count 以及下次请求的游标 msg_search_result_search_cursor。
2. 当界面滑动快到底部后根据上一次请求结果中的游标 msg_search_result_search_cursor 继续拉取下一页的数据 。
示例代码如下:
......
// 记录搜索游标
string searchCursor = "";
......

void searchConversation(string cursor) {
    List<string> keywordList = new List<string>();
    keywordList.add("test");
    MessageSearchParam searchParam = new MessageSearchParam
    {
      msg_search_param_keyword_array = keywordList,
      msg_search_param_conv_id = "",
      msg_search_param_search_count = 10,
      msg_search_param_search_cursor = cursor
    };

    TencentIMSDK.MsgSearchCloudMessages(searchParam, (int code, string desc, MessageSearchResult result, string user_data)=>{
        // 匹配到的消息所属的所有会话数量
        int totalCount = result.msg_search_result_total_count;
        // 下一页的游标
        searchCursor = result.msg_search_result_search_cursor;
        // 该页的根据消息会话分类的信息
        List<MessageSearchResultItem> resultItemList = result.msg_search_result_item_array;
        foreach (var resultItem in resultItemList) {
            // 会话 ID
            string conversationID = resultItem.msg_search_result_item_conv_id;
            // 该会话匹配到的所有消息数量
            int totalMessageCount = resultItem.msg_search_result_item_total_message_count;
            // 消息列表：如果 totalMessageCount > 1，该列表为空；如果 totalMessageCount = 1，该列表元素为此消息
            List<Message> messageList = resultItem.msg_search_result_item_message_array;
        }
    });
}

// 当需要加载下一页时
void loadMore() {
    searchConversation(searchCursor);
}

展示搜索指定会话的消息

与 搜索典型场景示例 图 2 展示会话列表不同的是，图 3 所示在指定会话中搜索到的消息列表。
为了防止内存膨胀，我们强烈建议您分页加载消息。举个例子，分页加载，每页展示 10 条消息结果：
1. 搜索参数 MessageSearchParam 可以参考如下设置：
设置搜索参数 MessageSearchParam 的 msg_search_param_conv_id 为搜索的会话 ID。
首次调用：设置参数 msg_search_param_search_count = 10，msg_search_param_search_cursor = ""。调用 MsgSearchCloudMessages 获取消息搜索结果，解析并展示到首页，并且从结果回调中获取会话总数量 msg_search_result_total_count 以及下一页的游标 msg_search_result_search_cursor。
再次调用：更新参数 msg_search_param_search_cursor 的值为上一步调用结果中的返回值。
2. 处理搜索结果 MessageSearchResult:
msg_search_result_total_count 表示该会话匹配到的所有消息数量。
msg_search_result_item_array 列表只有该会话的结果。列表中的元素 MessageSearchResultItem 的 msg_search_result_item_total_message_count 为该分页的消息数量，msg_search_result_item_message_array 为该分页的消息列表。
msg_search_result_search_cursor 表示下一页搜索的起始游标。
示例代码如下：
......
// 记录搜索游标
string searchCursor = "";
......

void searchMessage(String cursor) {
    List<string> keywordList = new List<string>();
    keywordList.add("test");
    MessageSearchParam searchParam = new MessageSearchParam
    {
      msg_search_param_keyword_array = keywordList,
      msg_search_param_conv_id = "conversationID",
      msg_search_param_search_count = 10,
      msg_search_param_search_cursor = cursor
    };
    TencentIMSDK.MsgSearchCloudMessages(searchParam, (int code, string desc, MessageSearchResult result, string user_data)=>{
        // 该会话匹配到的所有消息数量
        int totalMessageCount = result.msg_search_result_total_count;
        // 下一页的游标
        searchCursor = result.msg_search_result_search_cursor;
        // 该页消息信息
        List<MessageSearchResultItem> resultItemList = result.msg_search_result_item_array;
        foreach (var resultItem in resultItemList) {
            // 会话 ID
            string conversationID = resultItem.msg_search_result_item_conv_id;
            // 该页的消息数量
            int totalMessageCount = resultItem.msg_search_result_item_total_message_count;
            // 该页的消息数据列表
            List<Message> messageList = resultItem.msg_search_result_item_message_array;
        }
    });
}

// 当需要加载下一页时
void loadMore() {
    searchMessage(searchCursor);
}

搜索自定义消息

如果您希望自定义消息可以被搜到，在创建并发送自定义消息的时候，把需要搜索的文本放到 custom_elem_desc 字段中。
如果您配置了离线推送功能，设置参数 offline_push_config_desc 后，自定义消息也会有离线推送且通知栏展示该参数内容。
如果不需要离线推送，可以在发消息时将参数 message_offline_push_config 中的 offline_push_config_flag 字段设置为 kTIMOfflinePushFlag_NoPush 来控制。
如果推送的通知栏内容不想展示为被搜索的文本，可以用参数 message_offline_push_config 中的 offline_push_config_desc 来另外设置推送内容。

搜索富媒体消息

富媒体消息包含文件、图片、语音、视频消息。
对于文件消息，界面通常显示文件名。如果在发送消息时添加文件信息时传入 file_elem_file_name 参数，file_elem_file_name 会作为文件消息被搜索的内容，与搜索关键词进行匹配。如果未设置 file_elem_file_name，SDK 则会自动从 file_elem_file_path 提取文件名作为搜索内容。
file_elem_file_name 和 file_elem_file_path 信息会保存到本地和服务器，换设备拉取相关信息后均可搜索。
对于图片、语音、视频消息，并没有类似 file_elem_file_name 这种名称，界面通常显示缩略图或时长，此时指定 msg_search_param_keyword_array 搜索无效。
如果您希望搜索出此类消息，可以指定 msg_search_param_message_type_array 为 kTIMElem_Image/kTIMElem_Sound/kTIMElem_Video 做分类搜索，此时会搜索出所有指定类型的消息。
WebRTC Trtc Logo
Copyright © 2013-2025 Tencent RTC. All Rights Reserved.
  1. 隐私条款
  3. 法律
  5. Cookie政策
  7. 腾讯云