云信支持在客户端本地与云端存储历史消息，供后续查询。

前提条件

已在云信控制台开通消息漫游功能。步骤如下：

1. 在控制台首页应用管理选择应用进入应用配置页面，然后单击 IM即时通讯 专业版或 IM即时通讯 免费版下的功能配置按钮进入 IM 即时通讯配置页。

   

2. 在顶部选择全局功能页签，开启消息漫游功能。

   

3. 阅读并确认信息后，单击确认开启消息漫游功能。

本地历史消息

本地历史消息查询

传入一个已知的消息(锚点消息)，返回比这个消息更早的消息集合。如果没有已知的消息，则传入 nil，返回最新的消息集合。查询结果按照旧消息到新消息的顺序排列。

• 同步接口：

  @protocol NIMConversationManager <NSObject>
  /**
  *  从本地db读取一个会话里某条消息之前的若干条的消息
  *
  *  @param session 消息所属的会话
  *  @param message 当前最早的消息,没有则传入nil
  *  @param limit   个数限制
  *
  *  @return 消息列表，按时间从小到大排列
  */
  - (nullable NSArray<NIMMessage *> *)messagesInSession:(NIMSession *)session
                                              message:(nullable NIMMessage *)message
                                                  limit:(NSInteger)limit;
  @end
  

  参数说明：

  参数	类型	说明
  session	NIMSession	消息所属的会话
  message	NIMMessage	锚点消息
  limit	NSInteger	读取条数限制

  示例代码：

  // NIMSessionMsgDatasource.m
  
  - (void)resetMessages:(void(^)(NSError *error)) handler
  {    
      ...
      //获取到本地会话最后 limit 个消息并接到数据末尾
      NSArray<NIMMessage *> *messages = [[[NIMSDK sharedSDK] conversationManager] messagesInSession:_currentSession
                                                                                  message:nil
                                                                                      limit:_messageLimit];
      [self appendMessageModels:[self modelsWithMessages:messages]];
      ...
  }
  

• 异步接口

  @protocol NIMConversationManager <NSObject>
  /**
  *  从本地db读取一个会话里某条消息之前的若干条的消息
  *
  *  @param session 消息所属的会话
  *  @param message 当前最早的消息,没有则传入nil
  *  @param limit   个数限制
  *  @param completion 完成后的回调
  */
  - (void)messagesInSession:(NIMSession *)session
                  message:(NIMMessage *)message
                      limit:(NSInteger)limit
              completion:(NIMFetchMessageHistoryBlock)completion;
  @end
  

  参数说明：

  参数	类型	说明
  session	NIMSession	消息所属的会话
  message	NIMMessage	锚点消息
  limit	NSInteger	读取条数限制
  completion	NIMFetchMessageHistoryBlock	完成后的回调

按消息id查询

@protocol NIMConversationManager <NSObject>
/**
 *  根据消息Id获取消息
 *
 *  @param session    消息所属会话结合
 *  @param messageIds 消息Id集合
 *  @return 消息列表,按时间从小到大排列
 */
- (nullable NSArray<NIMMessage *> *)messagesInSession:(NIMSession *)session
                                           messageIds:(NSArray<NSString *> *)messageIds;
@end

参数说明：

删除本地消息

删除单条消息

调用此方法时，如果删除的是最后一条消息，消息所属的最近会话的 lastMessage 属性会自动变成上一条消息(没有则为空消息)，同时触发最近消息修改的回调。

NIMDeleteMessageOption 中可配置 removeFromDB。默认为 NO，即采用标记的方式进行消息删除。若设置为YES，则为完全删除，即SDK将记录此条消息的删除记录，即使从云端再次同步到该消息，也无法再从数据库里查询出来。

@protocol NIMConversationManager <NSObject>

/**
 *  删除某条消息
 *
 *  @param message 待删除的聊天消息
 *  @param option  删除选项。
 */
- (void)deleteMessage:(NIMMessage *)message 
               option:(nullable NIMDeleteMessageOption *)option;

@end

删除指定会话内消息

@protocol NIMConversationManager <NSObject>
/**
 *  删除某个会话的所有消息
 *
 *  @param session 待删除会话
 *  @param option 删除消息选项
 */
- (void)deleteAllmessagesInSession:(NIMSession *)session
                            option:(nullable NIMDeleteMessagesOption *)option;
@end

NIMDeleteMessagesOption 参数说明：

若想指定删除某一时间段内的消息，请使用以下接口：

@protocol NIMConversationManager <NSObject>
/**
 *  删除指定范围内的消息，如指定时间范围
 *
 *  @param session 目标会话
 *  @param option 删除消息选项
 */
- (void)deleteMessagesInSession:(NIMSession *)session 
                         option:(nullable NIMBatchDeleteMessagesOption *)option 
                     completion:(nullable NIMBatchDeleteMessagesBlock)block;
@end

NIMBatchDeleteMessagesOption 参数说明：

删除所有消息

@protocol NIMConversationManager <NSObject>
/**
 *  删除所有会话消息
 *
 *  @param option 删除消息选项
 *  @discussion 调用这个接口只会触发allMessagesDeleted这个回调，其他针对单个recentSession的回调都不会被调用
 */
- (void)deleteAllMessages:(NIMDeleteMessagesOption *)option
@end

云端历史消息

云端历史消息查询

@protocol NIMConversationManager <NSObject>
/**
 *  从服务器上获取一个会话里某条消息之前的若干条的消息
 *
 *  @param session 消息所属的会话
 *  @param option  搜索选项
 *  @param result  读取的消息列表结果
 *  @discussion    此接口不支持查询聊天室消息，聊天室请参考 NIMChatroomManagerProtocol 中的查询消息接口。
 *
 */
- (void)fetchMessageHistory:(NIMSession *)session
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(nullable NIMFetchMessageHistoryBlock)result;
@end

其中 option 为搜索选项，具体选项如下:

删除云端历史消息

删除单会话云端历史消息

@protocol NIMConversationManager <NSObject>

/**
 *  清空点对点会话的服务端的消息。不会删除本地的消息记录。
 *
 *  @param session 目标会话
 *  @param option 清空消息选项
 *  @param completion 完成回调
 *  @discussion 只支持点对点，清空本用户服务端消息，不影响对方；如果不设置清空选项，服务端默认会同时清空漫游消息；
 */
- (void)deleteSelfRemoteSession:(NIMSession *)session
                         option:(nullable NIMClearMessagesOption *)option
                     completion:(nullable NIMRemoveRemoteSessionBlock)completion;              
@end

属性列表

删除单条云端历史消息

@protocol NIMConversationManager <NSObject>

/**
 *  删除本地某条消息，并同时删除服务端历史、漫游
 *
 *  @param message 待删除的聊天消息
 *  @param ext 扩展字段
 *  @param completion 完成回调
 */
- (void)deleteMessageFromServer:(NIMMessage *)message 
                            ext:(nullable NSString *)ext 
                     completion:(nullable NIMRemoveRemoteMessageBlock)block         
@end

批量删除云端历史消息

@protocal NIMConversationManager <NSObject>

/**
 * 批量删除消息，同时删除服务端和本地。所有传入的消息必需属于同一个会话。
 *
 * @param messages 消息数组
 * @param exts key为消息id，value为删除该消息所对应的扩展信息
 * @param completion 删除完成的回调
 */
- (void)deleteRemoteMessages:(NSArray<NIMMessage *> *)messages
                        exts:(nullable NSDictionary<NSString *,NSString *> *)exts
                  completion:(nullable NIMDeleteRemoteMessagesCompletionBlock)completion;

@end

清空单个会话的云端历史消息

@protocol NIMConversationManager <NSObject>
  
 /**
 * 删除某个会话的所有本地和云端的历史消息。删除后，查询云端消息历史的接口将不能返回这些消息。
 *
 * @param session 目标会话
 * @param options 清空消息历史的可选项
 * @param block 清空完成后的回调
 */
- (void)deleteAllRemoteMessagesInSession:(NIMSession *)session
                                 options:(NIMSessionDeleteAllRemoteMessagesOptions *)options
                              completion:(NIMSessionDeleteAllRemoteMessagesCompletionBlock)completion;
@end

属性列表

消息检索

SDK当前支持消息检索。

本地消息检索

根据会话检索

@protocol NIMConversationManager <NSObject>
/**
 *  搜索本地会话内消息
 *
 *  @param session 消息所属的会话
 *  @param option  搜索选项
 *  @param result  读取的消息列表结果
 *
 */
- (void)searchMessages:(NIMSession *)session
                option:(NIMMessageSearchOption *)option
                result:(nullable NIMSearchMessageBlock)result;
@end

其中 option 为搜索选项，具体选项如下:

搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。

根据关键词搜索最新 100 条消息的内容示例:

NIMMessageSearchOption *option = [[NIMMessageSearchOption alloc] init];
option.searchContent = @"keyWord";
option.fromIds       = uids;
option.limit         = 100;
option.allMessageTypes = YES;

[[NIMSDK sharedSDK].conversationManager searchMessages:session option:option result:^(NSError * _Nullable error, NSArray<NIMMessage *> * _Nullable messages) {
    // do something with messages
}];

本地全局检索

@protocol NIMConversationManager <NSObject>
/**
 *  全局搜索本地消息
 *
 *  @param option 搜索选项
 *  @param result 读取的消息内容
 */
- (void)searchAllMessages:(NIMMessageSearchOption *)option
                result:(NIMGlobalSearchMessageBlock)result
@end

其中 option 为搜索选项，具体选项如下:

搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。

搜索全局的图片和视频的最新 100 条消息示例：

NIMMessageSearchOption *option = [[NIMMessageSearchOption alloc] init];
option.limit = 100;

[[NIMSDK sharedSDK].conversationManager searchAllMessages:option result:^(NSError * _Nullable error, NSDictionary<NIMSession *,NSArray<NIMMessage *> *> * _Nullable messages) { }];

云端消息关键字检索

根据关键字查询服务端历史消息的文本内容，可另外通过指定设置起、止时间完成分页等功能；支持点对点、群（暂不支持超大群）;

/**
 *  会话管理器
 */
@protocol NIMConversationManager <NSObject>
/**
*  根据关键字从服务器上检索消息
*
*  @param session 消息所属的会话
*  @param option  检索选项
*  @param result  读取的消息列表结果
*  @discussion    检索消息内容，大小写不敏感；此接口不支持查询聊天室消息，聊天室请参考 NIMChatroomManagerProtocol 中的消息接口。
*
*/
- (void)retrieveServerMessages:(NIMSession *)session
                        option:(NIMMessageServerRetrieveOption *)option
                        result:(nullable NIMRetrieveServerMessagesBlock)result;
@end

属性列表

示例

	NSString * keyword = searchBar.text;
    NIMMessageServerRetrieveOption * option = [[NIMMessageServerRetrieveOption alloc] init];
    option.keyword = keyword;
    [[NIMSDK sharedSDK].conversationManager retrieveServerMessages:self.session
                                                            option:option
                                                            result:^(NSError * _Nullable error,
                                                                     NSArray<NIMMessage *> * _Nullable messages)
    {
     ...
    }];

全文云端消息检索

开启全文云端消息检索功能

使用全文云端消息检索功能前，需在云信控制台进行开启，步骤如下：

1. 在控制台首页应用管理选择应用进入应用配置页面，然后单击 IM即时通讯 专业版下的功能配置按钮进入 IM 即时通讯配置页。

   

2. 在顶部选择全局功能页签，开启全文云端消息检索功能。

   

3. 阅读并确认信息后，单击确认开启全文云端消息检索功能。

全文云端消息检索（按会话聚合排列）

@protocol NIMConversationManager <NSObject>
/**
 *  根据关键字从服务器上全量检索消息
 *
 *  @param option  检索选项
 *  @param result  读取的消息列表结果
 *  @discussion    检索消息内容，此接口仅支持查询P2P和群聊消息，不支持聊天室和超大群
 *
 */
- (void)retrieveServerMessages:(NIMMessageFullKeywordSearchOption *)option
                        result:(nullable NIMRetrieveServerMessagesBlock)result;
@end

属性列表

MsgFullKeywordSearchConfig属性表

• 示例

[[NIMSDK sharedSDK].conversationManager retrieveServerMessages:session
                                                        option:option
                                                        result:^(NSError * _Nullable error, NSArray<NIMMessage *> * _Nullable messages)
{
    if (error)
    {
        NSAssert(NO, @"检索消息关键字失败");
    }
     dispatch_group_leave(group);
}];

全文云端消息检索(按消息时间排列)

@protocol NIMConversationManager <NSObject>
/**
 * 云端历史消息全文检索（按时间排序，不按会话分组）
 *
 * @param option 检索选项，其中sessionLimit为无效变量
 * @param result  读取的消息列表结果
 * @discussion    检索消息内容
 */
- (void)retrieveServerMessagesOrderByTime:(NIMMessageFullKeywordSearchOption *)option
                                   result:(nullable NIMRetrieveServerMessagesBlock)result;
@end

属性列表

MsgFullKeywordSearchConfig属性表

动态查询历史消息

为了获取完整的历史消息记录，您可以使用全云端方案，即用户每次进入时都通过查询云端历史记录并将查到的消息同步至本地。但是在会话多、消息多的场景下，使用全云端方案，会导致耗时长，耗能大等问题。

为解决上述问题，云信 IM 提供本地+云端智能调度方案，通过调用完整的内部逻辑保证历史消息的连续性和完整性。您仅需要选择开始或结束时间戳以及对应的消息条数即可按需获取历史消息。

开启动态查询历史消息功能

请先在云信控制台开通动态查询历史消息功能，否则该接口只会从本地数据库获取消息。

1. 在控制台首页应用管理选择应用进入应用配置页面，然后单击 IM即时通讯 专业版下的功能配置按钮进入 IM 即时通讯配置页。

   

2. 在顶部选择全局功能页签，开启动态查询历史消息功能。

   

3. 阅读并确认信息后，单击确认开启动态查询历史消息功能。

接口说明

通过调用 getMessagesDynamically: 方法动态查询连续的历史消息。

参数说明：

回调结果说明：

//查询最新的 100 条历史消息
NIMGetMessagesDynamicallyParam *param = [[NIMGetMessagesDynamicallyParam alloc] init];
param.session = [NIMSession session:sessionId type:sessionType];
param.limit = 100;
[[[NIMSDK sharedSDK] conversationManager] getMessagesDynamically:param completion:^(NSError * __nullable error, BOOL isReliable, NSArray<NIMMessage *> * __nullable messages) {
    if (error)
    {
        // 失败
        return;
    }
    if (isReliable)
    {
        // 查到的消息是可信（连续）的，消息列表的顺序默认为从新往旧
    }
    else
    {
        // 查到的消息是不可信（不连续）的，消息列表的顺序默认为从新往旧
    }
}];

NIMGetMessagesDynamicallyParam *param = [[NIMGetMessagesDynamicallyParam alloc] init];
param.session = [message session];
param.limit = 100;
param.endTime = [message timestamp];
param.anchorServerId = [message serverID];
param.anchorClientId = [message messageId];

[[[NIMSDK sharedSDK] conversationManager] getMessagesDynamically:param completion:^(NSError * __nullable error, BOOL isReliable, NSArray<NIMMessage *> * __nullable messages) {
    if (error)
    {
        // 失败
        return;
    }
    if (isReliable)
    {
        // 查到的消息是可信（连续）的，消息列表的顺序默认为从新往旧
    }
    else
    {
        // 查到的消息是不可信（不连续）的，消息列表的顺序默认为从新往旧
    }
}];

NIMGetMessagesDynamicallyParam *param = [[NIMGetMessagesDynamicallyParam alloc] init];
param.session = [message session];
param.limit = 100;
param.order = NIMMessageSearchOrderAsc ;
param.startTime = [message timestamp];
param.anchorServerId = [message serverID];
param.anchorClientId = [message messageId];

[[[NIMSDK sharedSDK] conversationManager] getMessagesDynamically:param completion:^(NSError * __nullable error, BOOL isReliable, NSArray<NIMMessage *> * __nullable messages) {
    if (error)
    {
        // 失败
        return;
    }
    if (isReliable)
    {
        // 查到的消息是可信（连续）的，消息列表的顺序为从旧往新（与查询时设置的order一致）
    }
    else
    {
        // 查到的消息是不可信（不连续）的，消息列表的顺序为从旧往新（与查询时设置的order一致）
    }
}];