聊天扩展

功能概述

聊天扩展提供聊天会话相关扩展功能(v7.6.0),包括 会话消息回复消息快捷评论会话置顶收藏夹会话消息PIN标记等。所有功能包含在 NIMChatExtendManager 协议中,所以回调通过NIMChatExtendManagerDelegate上抛。

会话消息回复

会话消息回复可以对目标消息进行回复,形成父、子消息的逻辑结构,一条消息可以有0或者一条父消息;父消息可以有0或者n条子消息;消息的父消息通过threadMessageId等获取,该消息回复的消息通过repliedMessageId等获取;

回复一条消息

@protocol NIMChatExtendManager <NSObject>
/**
 *  回复消息
 *
 *  @param message 新生成的消息
 *  @param target  被回复的消息
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 是否调用成功,这里返回的 result 只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器
 */
- (BOOL)reply:(NIMMessage *)message
           to:(NIMMessage *)target
        error:(NSError * __nullable *)error;
@end

属性列表

参数 类型 说明
message NIMMessage 新消息
target NIMMessage 被回复的目标消息
error NSError 接口调用结果

示例

 NIMMessage *repliedMessage = [self.sessionConfig threadMessage];
 [[[NIMSDK sharedSDK] chatExtendManager] reply:newWessage
                                            to:repliedMessage
                                         error:nil];

本地获取子消息列表

子消息列表接口不会返回删除的消息(DB删除的除外),也不包括撤回消息等;子消息数目会算上被删除的消息以及撤回消息等。

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  本地获取Thread Talk的消息列表
 *
 *  @param  message 父消息
 *  @return 目标message的子消息列表
 */
- (NSArray<NIMMessage *> * _Nullable)subMessages:(NIMMessage *)message;

/**
 *  本地获取Thread Talk的消息列表
 *
 *  @param  message 父消息
 *  @return 目标message的子消息数目
 */
- (NSInteger)subMessagesCount:(NIMMessage *)message;
@end

属性列表

参数 类型 说明
message NIMMessage 待查询消息

示例

NSArray *subMessages = [[NIMSDK sharedSDK].chatExtendManager subMessages:message];
model.childMessages = subMessages;
model.childMessagesCount = [[NIMSDK sharedSDK].chatExtendManager subMessagesCount:message];

从云端获取子消息

从云端获取该消息的子消息列表

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  获取指定消息的Thread Talk子消息
 *
 *  @param message 目标消息
 *  @param option  查询分页选项
 *  @param block   完成回调
 */
- (void)fetchSubMessagesFrom:(NIMMessage *)message
                      option:(NIMThreadTalkFetchOption * _Nullable)option
                  completion:(NIMThreadTalkFetchMessages)block;
@end

属性列表

参数 类型 说明
message NIMMessage 待查询消息
option NIMThreadTalkFetchOption 查询选项
block NIMThreadTalkFetchMessages 结果回调

示例

NIMThreadTalkFetchOption *option = [[NIMThreadTalkFetchOption alloc] init];
option.limit = 100; // 默认为0
option.excludeMessage = firstMessage; // 返回结果里不包含这条消息
option.end = firstMessage.timestamp;
option.sync = YES; // 同步到SDK 的DB中,如果已经存在则忽略
option.reverse = NO;

[[NIMSDK sharedSDK].chatExtendManager fetchSubMessagesFrom:self.threadMessage option:option completion:^(NSError * error, NIMThreadTalkFetchResult * result)
{
    //TODO...
}

云端消息获取(补偿机制)

为了防止消息漫游过期等情况下消息未同步到本地,可通过消息ID从云端获取消息详情,并可选择同步到本地;

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  根据MessageId等获取消息
 *
 *  @param infos    请求信息
 *  @param sync     是否同步到本地,注:DB标记状态删除的消息无法被同步覆盖
 *  @param block    完成回调
 */
- (void)fetchHistoryMessages:(NSArray<NIMChatExtendBasicInfo *> *)infos
                    syncToDB:(BOOL)sync
                  completion:(NIMFetchHistoryMessagesByIds)block;
@end

属性列表

参数 类型 说明
infos NSArray 待查询消息的基本信息
sync BOOL 是否同步到SDK 的DB
block NIMFetchHistoryMessagesByIds 结果回调

示例

 [[NIMSDK sharedSDK].chatExtendManager fetchHistoryMessages:@[info]
                                                   syncToDB:YES
                                                 completion:^(NSError * error, NSMapTable<NIMChatExtendBasicInfo *,NIMMessage *> * result)
    {
        // TODO
    }];

消息快捷评论

添加评论

对一条消息进行快捷评论,对于同一个添加者,同一条消息的同一类型只能添加一次,否者会被后添加的评论覆盖。

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  发送快捷回复
 *
 *  @param comment      回复内容
 *  @param message      被回复消息
 *  @param completion   完成回调
 */
- (void)addQuickComment:(NIMQuickComment *)comment
              toMessage:(NIMMessage *)message
             completion:(NIMQuickCommentHandler _Nullable)completion;
@end

属性列表

参数 类型 说明
comment NIMQuickComment 评论内容
message NIMMessage 目标消息
completion NIMQuickCommentHandler 评论是否成功的回调

示例

 [[NIMSDK sharedSDK].chatExtendManager addQuickComment:comment
                                                toMessage:message
                                               completion:^(NSError * _Nullable error)
    {
        //TODO ...

    }];

删除评论

对一条消息进行快捷评论,对于同一个添加者,同一条消息的同一类型只能添加一次,否者会被后添加的评论覆盖。

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  从服务端删除一条评论
 *
 *  @param comment      目标评论
 *  @param completion   完成回调
 */
- (void)deleteQuickComment:(NIMQuickComment *)comment
                completion:(NIMQuickCommentHandler _Nullable)completion;
@end

属性列表

参数 类型 说明
comment NIMQuickComment 评论内容
completion NIMQuickCommentHandler 评论是否成功的回调

示例

[[NIMSDK sharedSDK].chatExtendManager deleteQuickComment:comment
                                                  completion:^(NSError * _Nullable error)
    {
       //TODO...
    }];

查询评论

查询建议使用可靠数据接口 fetchQuickComments: completion:,该接口保证评论列表是完整的。该接口在本地数据无法判断完整性的情况下第一次会去服务端查询、同步,单次登录、单个会话只会向服务端请求一次,后面会从本地获取(数据确定是完整的)。

注: 该接口本地会过滤掉一些无效的传入消息,如被服务端反垃圾的消息,本地自己构造的消息等

原型

@protocol NIMChatExtendManager <NSObject>
/**
 *  批量获取快捷评论
 *
 *  @param messages 目标消息, 最多批量20个
 *  @param completion 完成回调
 */
- (void)fetchQuickComments:(NSArray<NIMMessage *> *)messages
                completion:(NIMFetchCommentsByMsgsHandler)completion;
@end
参数 类型 说明
messages NSArray * 待查询的消息列表
completion NIMFetchCommentsByMsgsHandler 结果回调

会话置顶

使用前请务必打开 置顶会话同步开关。如果不使用置顶功能建议关闭(默认),有利于节省流量。

[[NIMSDKConfig sharedConfig] setShouldSyncStickTopSessionInfos:YES];

置顶记录实体 NIMStickTopSessionInfo

参数 类型 说明
session NIMSession 置顶记录对应的会话
ext NSString 扩展字段,最大512字符
createTime NSTimeInterval 创建时间(s)
updateTime NSTimeInterval 更新时间(s)

添加一条置顶记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 添加一条置顶记录
 * @param params 添加置顶的参数
 * @param completion 添加置顶记录完成的回调
 */
- (void)addStickTopSession:(NIMAddStickTopSessionParams *)params 
                completion:(nullable NIMAddStickTopSessionCompletion)completion;
@end

参数 NIMAddStickTopSessionParams

参数 类型 说明
session NIMSession 置顶记录对应的会话
ext NSString 扩展字段,最大512字符

例:

NIMAddStickTopSessionParams *params = [[NIMAddStickTopSessionParams alloc] initWithSession:session];
[NIMSDK.sharedSDK.chatExtendManager addStickTopSession:params completion:^(NSError *         _Nullable error, NIMStickTopSessionInfo * _Nullable newInfo) {
    if (error) {
      // handle error
      return;
    }
    // Do something with {newInfo}
}];

删除一条置顶记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 删除一条置顶记录
 * @param info 需要删除的置顶记录
 * @param completion 删除完成的回调
 */
- (void)removeStickTopSession:(NIMStickTopSessionInfo *)info 
                   completion:(nullable NIMRemoveStickTopSessionCompletion)completion;
@end

参数 info 必须字段

参数 类型 说明
session NIMSession 置顶记录对应的会话
ext NSTimeInterval 创建时间(s)

例:

[NIMSDK.sharedSDK.chatExtendManager removeStickTopSession:info completion:^(NSError * _Nullable error, NIMStickTopSessionInfo * _Nullable removedInfo) {
    if (error) {
      // handle error
      return;
    }
      // Do something with {removedInfo}
}];

更新置顶记录的扩展信息

@protocol NIMChatExtendManager <NSObject>
/**
 * 更新一条置顶记录的扩展信息
 * @param info 需要更新的置顶记录
 * @param completion 删除完成的回调
 */
- (void)udpateStickTopSession:(NIMStickTopSessionInfo *)info 
                   completion:(nullable NIMUpdateStickTopSessionCompletion)completion;
@end

参数 info 必须字段

参数 类型 说明
session NIMSession 置顶记录对应的会话
createTime NSTimeInterval 创建时间(s)
ext NSString 扩展字段,最大512字符,不传表示删除ext字段

例:

[NIMSDK.sharedSDK.chatExtendManager updateStickTopSession:info completion:^(NSError * _Nullable error, NIMStickTopSessionInfo * _Nullable updatedInfo) {
        if (error) {
            // handle error
        return;
        }
      // Do something with {removedInfo}
}];

查找所有置顶记录

查找当前用户的所有置顶记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 查找所有的置顶记录
 * @param completion 查找完成的回调
 */
- (void)loadStickTopSessionInfos:(nullable NIMLoadStickTopSessionInfosCompletion)completion;
@end

例:

[NIMSDK.sharedSDK.chatExtendManager loadStickTopSessionInfos:^(NSError * _Nullable error, NSDictionary<NIMSession *,NIMStickTopSessionInfo *> * _Nullable infos) {
        if (error) {
            // handle error
        return;
        }
      // Do something with {infos}
}];

获取含置顶的会话列表

获取已经根据置顶信息排序的最近会话(推荐👍)

@protocol NIMChatExtendManager <NSObject>
/**
 * 获取最近会话列表
 * @param options 查询选项(如按照置顶会话排序)
 */
- (void)loadRecentSessionsWithOptions:(NIMLoadRecentSessionsOptions *)options 
                          completion:(nullable NIMLoadRecentSessionsCompletion)completion;
@end

参数 NIMLoadRecentSessionsOptions

参数 类型 说明
sortByStickTopInfos BOOL 是否按照置顶会话排序

例:

NIMLoadRecentSessionsOptions *options = [[NIMLoadRecentSessionsOptions alloc] init];
options.sortByStickTopInfos = YES;
[NIMSDK.sharedSDK.chatExtendManager loadRecentSessionsWithOptions:options completion:^(NSError * _Nullable error, NSArray<NIMRecentSession *> * _Nullable recentSessions) {
        if (error) {
            // handle error
        return;
        }
      // Do something with {recentSessions}
}];

根据置顶记录排序

根据置顶记录排序 最近会话

@protocol NIMChatExtendManager <NSObject>
/**
 * 根据置顶信息排序最近会话
 * @param recentSessions 需要排序的置顶会话,若传可变数组则进行in place排序
 * @param infos [会话:置顶信息] 映射
 * @return 排序后的最近会话列表,若传如可变数组,则返回其数组本身
 */
- (NSArray<NIMRecentSession *> *)sortRecentSessions:(NSArray<NIMRecentSession *> *)recentSessions         
                                  withStickTopInfos:(NSDictionary<NIMSession *,NIMStickTopSessionInfo *> *)infos;
@end                                 

例:

NSMutableArray<NIMRecentSession *> *mutableSessions = ...;
NSDictionary<NIMSession *,NIMStickTopSessionInfo *> *infos = ...;
[NIMSDK.sharedSDK.chatExtendManager sortRecentSessions: mutableSessions]; // 原地排序
// Do something with {mutableSessions}

查询某个会话的置顶记录

查询某个会话的置顶记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 查询某个会话的置顶信息
 * @param session 需要查询的会话
 * @return 置顶信息
 */
- (NIMStickTopSessionInfo *)stickTopInfoForSession:(NIMSession *)session;
@end

例:

NIMStickTopSessionInfo *info = [NIMSDK.sharedSDK.chatExtendManager stickTopInfoForSession:session];
if (info) {
      // Do something with {info}
}

收藏夹

查询当前用户的收藏内容

@protocol NIMChatExtendManager <NSObject>
/**
 * 分页查询收藏列表
 * @param option 分页查询选项
 * @param completion 查询完成的回调
 */
- (void)queryCollect:(NIMCollectQueryOptions *)options 
          completion:(nullable NIMCollectQueryBlock)completion;
@end

参数 NIMCollectQueryOptions

参数 类型 说明
fromTime NSTimeInterval 最小时间(s)
toTime NSTimeInterval 最大时间,传0表示当前时间(s)
excludeId NSInteger 上一页最后一条ID,第一条传0
limit NSInteger 查询条数,默认100
reverse BOOL 是否倒序
type NSInteger 收藏类型

返回收藏记录数组项 NIMCollectInfo

参数 类型 说明
Id NSUInteger 收藏项id
type NSInteger 收藏类型
data NSString 数据,最大20KB
ext NSString 扩展字段,最大1KB
uniqueId NSString 去重唯一ID
createTime NSTimeInterval 创建时间(s)
updateTime NSTimeInterval 更新时间(s)

例:

NIMCollectQueryOptions *options = [[NIMCollectQueryOptions alloc] init];
options.toTime = ...;
options.excludeId = ...;
options.type = ...;
[NIMSDK.sharedSDK.chatExtendManager queryCollect:self.queryOptions completion:^(NSError * _Nullable error, NSArray<NIMCollectInfo *> * _Nullable collectInfos, NSInteger totalCount) {
  if (error) {
    // Handle error
    return;
  }
  // Do something with {collectInfos} and {totalCount}
}];

totalCount返回当前用户对应type的所有收藏条数,可用来判断是否已经加载到最后一页

添加一条收藏

添加一条收藏

@protocol NIMChatExtendManager <NSObject>
/**
 * 添加一条收藏
 * @param info 添加收藏的参数,必须字段:type、data、ext
 * @param completion 添加完成的回调
 */
- (void)addCollect:(NIMAddCollectParams *)info 
        completion:(nullable NIMAddCollectBlock)completion;
@end

参数 NIMAddCollectParams

参数 类型 说明
type NSInteger 收藏类型
data NSString 数据,最大20KB
ext NSString 扩展字段,最大1KB
uniqueId NSString 去重唯一ID

例:

NIMAddCollectParams *params = [[NIMAddCollectParams alloc] init];
params.data = ...;
params.type = ...;
params.uniqueId = ...; 
[[NIMSDK sharedSDK].chatExtendManager addCollect:params completion:^(NSError * _Nullable error, NIMCollectInfo * _Nullable collectInfo) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {collectInfo}
}];

移除收藏

@protocol NIMChatExtendManager <NSObject>
/**
 * 批量移除收藏
 * @param collectList 批量移除的收藏对象,必须字段:id、createTime
 * @param completion 移除完成的回调
 */
- (void)removeCollect:(NSArray<NIMCollectInfo *> *)collectList 
           completion:(nullable NIMRemoveCollectBlock)completion;
@end

参数数组项 NIMCollectInfo 必须字段

参数 类型 说明
id NSUInteger 收藏项id
createTime NSTimeInterval 创建时间(s)

例:

NSArray<NIMCollectInfo> *collectList = ...;
[NIMSDK.sharedSDK.chatExtendManager removeCollect:collectList completion:^(NSError * _Nullable error, NSInteger total_removed) {
    if (error) {
        // Handle error
        return;
    }
    // Successfully removed {total_removed} infos
}];

更新收藏扩展字段

@protocol NIMChatExtendManager <NSObject>
/**
 * 更新收藏ext
 * @param collectInfo 需要更新的收藏对象,需要id、createTime、ext字段,如果ext不传,表示删除ext字段
 */
- (void)updateCollect:(NIMCollectInfo *)collectInfo 
           completion:(nullable NIMUpdateCollectBlock)completion;
@end

参数 NIMCollectInfo 必传字段

参数 类型 说明
id NSUInteger 收藏项id
createTime NSTimeInterval 创建时间(s)
ext NSString 扩展字段,最大1KB,不传表示删除ext

例:

NIMCollectInfo *info = ...; 
info.ext = "New ext"; //
[[NIMSDK sharedSDK].chatExtendManager updateCollect:params completion:^(NSError * _Nullable error, NIMCollectInfo * _Nullable collectInfo) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {collectInfo}
}];

PIN标记

PIN标记实体 NIMMessagePinItem

参数 类型 说明
session NIMSession 所属会话
messageFromAccount NSString 消息发送方ID
messageToAccount NSString 消息接收方ID
messageTime NSTimeInterval 消息时间戳(s)
messageServerID NSString 服务端消息ID
messageId NSString 本地消息ID
accountID NSString 操作者,不传表示当前登录者
ext NSString 扩展字段,string,最大512B
createTime NSTimeInterval 创建时间(s)
updateTime NSTimeInterval 更新时间(s)

根据要操作的消息快捷创建 NIMMessagePinItem 对象

NIMMessage *message = ...;
NIMMessagePinItem *pinItem = [[NIMMessagePinItem alloc] initWithMessage:message];

添加一条PIN记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 添加一条PIN记录
 * @param item 需要添加的PIN记录
 * @param completion 添加完成的回调
 */
- (void)addMessagePin:(NIMMessagePinItem *)item 
           completion:(nullable NIMAddMessagePinCompletion)completion;
@end

例:

NIMMessage *message = ...;
NIMMessagePinItem *pinItem = [[NIMMessagePinItem alloc] initWithMessage:message];
[NIMSDK.sharedSDK.chatExtendManager addMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

删除一条PIN记录

删除一条PIN记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 删除一条PIN记录
 * @param item 需要删除的PIN记录
 * @param completion 删除完成的回调
 */
- (void)removeMessagePin:(NIMMessagePinItem *)item 
              completion:(nullable NIMRemoveMessagePinCompletion)completion;
@end

例:

NIMMessagePinItem *pinItem = ...;
[NIMSDK.sharedSDK.chatExtendManager removeMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

更新一条PIN记录的扩展字段

@protocol NIMChatExtendManager <NSObject>
/**
 * 更新一条PIN记录的扩展字段(ext)
 * @param item 需要更新的PIN记录,ext不传为删除
 * @param completion 更新完成的回调
 */
- (void)updateMessagePin:(NIMMessagePinItem *)item 
              completion:(nullable NIMUpdateMessagePinCompletion)completion;
@end

例:

NIMMessagePinItem *pinItem = ...;
pinItem.ext = @"New ext";
[NIMSDK.aredSDK.chatExtendManager updateMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

查询全部PIN记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 查询全部PIN记录(登录后首次查询该会话会触发一次网络同步)
 * @param session 需要查询的会话
 * @param completion 加载完成的回调
 */
- (void)loadMessagePinsForSession:(NIMSession *)session 
                       completion:(nullable NIMLoadMessagePinsCompletion)completion;
@end

如注释所说,登录期间首次调用会触发一次网络同步,其余时间将不同步

参数说明

参数 类型 说明
session NIMSession 需要查询的会话

例:

[NIMSDK.sharedSDK.chatExtendManager loadMessagePinsForSession:_currentSession completion:^(NSError * _Nonnull error, NSArray<NIMMessagePinItem *> * _Nullable items) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {items}
}];

查询某条消息的PIN记录

查询某条消息的PIN记录

@protocol NIMChatExtendManager <NSObject>
/**
 * 查询某条消息的PIN记录
 * @param message 需要查询的消息
 * @return 记录
 */
- (NIMMessagePinItem *)pinItemForMessage:(NIMMessage *)message;
@end

参数说明

参数 类型 说明
message NIMMessage 需要查询的消息

聊天扩展事件监听

//添加事件代理
[NIMSDK.sharedSDK.chatExtendManager addDelegate:self];

//移除事件代理
[NIMSDK.sharedSDK.chatExtendManager removeDelegate:self];

代理协议 NIMChatExtendManagerDelegate

/**
 *  聊天扩展回调
 */
@protocol NIMChatExtendManagerDelegate <NSObject>

#pragma mark - 快捷回复
@optional

/**
 *  新增快捷评论
 *
 *  @param comment 评论
 */
- (void)onRecvQuickComment:(NIMQuickComment *)comment;

/**
 *  移除快捷评论
 *
 *  @param comment 被删评论
 */
- (void)onRemoveQuickComment:(NIMQuickComment *)comment;

/**
 * 一条PIN被增加的在线通知
 * @param item 新增的PIN记录
 */
- (void)onNotifyAddMessagePin:(NIMMessagePinItem *)item;

/**
 * 一条PIN被移除的在线通知
 * @param item 被移除的PIN记录
 */
- (void)onNotifyRemoveMessagePin:(NIMMessagePinItem *)item;

/**
 * 一条PIN被更新的在线通知
 * @param item 被更新的PIN记录
 */
- (void)onNotifyUpdateMessagePin:(NIMMessagePinItem *)item;

/**
 * 置顶会话同步完成的在线通知
 * @param response 置顶信息全量同步后的响应对象
 */
- (void)onNotifySyncStickTopSessions:(NIMSyncStickTopSessionResponse *)response;

/**
 * 一条置顶信息被增加的在线通知
 * @param newInfo 新增的置顶信息
 */
- (void)onNotifyAddStickTopSession:(NIMStickTopSessionInfo *)newInfo;

/**
 * 一条置顶信息被移除的在线通知
 * @param removedInfo 被移除的置顶信息
 */
- (void)onNotifyRemoveStickTopSession:(NIMStickTopSessionInfo *)removedInfo;

/**
 * 一条置顶会话被更新的在线通知
 * @param updatedInfo 被更新的置顶信息
 */
- (void)onNotifyUpdateStickTopSession:(NIMStickTopSessionInfo *)updatedInfo;
@end