IM 即时通讯
iOS
开发指南

聊天室

更新时间: 2023/09/05 16:41:06

本文已废弃,请前往聊天室概述聊天室功能文档查看相关说明。

功能概述

云信提供聊天室功能,人数无上限,用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端API来完成。

聊天室原型:

@interface NIMChatroom : NSObject
/**
 *  聊天室Id
 */
@property (nullable,nonatomic,copy)     NSString    *roomId;

/**
 *  聊天室名
 */
@property (nullable,nonatomic,copy)     NSString    *name;

/**
 *  公告
 */
@property (nullable,nonatomic,copy)     NSString    *announcement;


/**
 *  创建者
 */
@property (nullable,nonatomic,copy)     NSString    *creator;


/**
 *  第三方扩展字段,长度限制4K
 */
@property (nullable,nonatomic,copy)     NSString *ext;

/**
 *  当前在线用户数量
 */
@property (nonatomic,assign)   NSInteger onlineUserCount;

/**
 *  直播地址。当与直播业务搭配时,可以将直播推拉流地址设置于此。
 */
@property (nullable,nonatomic,copy)   NSString *broadcastUrl;

/**
 *  聊天室队列修改权限等级
 */
@property (nonatomic,assign)   NIMChatroomQueueModificationLevel queueModificationLevel;

/**
 *  聊天室是否正在全员禁言标记,禁言后只有管理员可以发言
 */
- (BOOL)inAllMuteMode;
@end

进入聊天室

用户要在聊天室收发消息之前,必须先调用接口进入聊天室。聊天室只允许用户手动进入,无法进行邀请。支持同时进入10个聊天室。

进入聊天室可以有两种方式:以独立模式进入聊天室和非独立模式进入聊天室。

  • 独立模式是指在IM处于未登录的情况下,进入聊天室的方式,针对只需要聊天室功能的业务场景。

  • 非独立模式是指先完成IM登录,再进入聊天室的方式,针对需要IM和聊天室功能的业务场景。

  • 由进入聊天室方法中的NIMChatroomIndependentMode参数设置聊天室的模式,默认为 非独立模式。

@protocol NIMChatroomManager <NSObject>
/**
 *  进入聊天室
 *
 *  @param request    进入聊天室请求
 *  @param completion 进入完成后的回调
 */
- (void)enterChatroom:(NIMChatroomEnterRequest *)request
           completion:(NIMChatroomEnterHandler)completion;
@end           

NIMChatroomEnterRequest 参数列表

参数
类型
说明
roomId NSString 聊天室 ID
roomNickname NSString 聊天室昵称
roomAvatar NSString 聊天室头像,上层可以自主设置在聊天室内的头像,没有设置则使用用户本身的信息
roomExt NSString 本人的聊天室成员信息拓展字段,仅对当次进入有效
roomNotifyExt NSString 聊天室事件通知拓展字段
tags NSString 登录标签,可以设置多个,json_array格式,例子:["tag1", "tag2"]
notifyTargetTags NSString 登录登出通知的目标标签,是一个标签表达式,见TagCalculator和TagPattern
retryCount NSInteger 聊天室重连次数,默认为三次,设置成 0 后一旦一次连接失败后,SDK 将不在重试。 APP 可以根据自己的需求进行设置
mode NIMChatroomIndependentMode 聊天室独立模式. 默认为 nil。
loginAuthType NIMChatroomLoginAuthType 鉴权方式
dynamicTokenHandler NIMProvideChatroomDynamicTokenHandler 动态token回调
loginExt NSString 扩展字段
locationX NSDecimalNumber 坐标x
locationY NSDecimalNumber 坐标y
locationZ NSDecimalNumber 坐标z
distance NSDecimalNumber 订阅的消息的距离
antispamBusinessId NSString 对某些资料内容另外的反垃圾的业务ID

其中:

  • 进入聊天室时设置。每次消息中都会带上的扩展 roomExt,这个字段可以放入用户在聊天室的自定义信息,如权限,头衔等等。当本方发出消息或者进行聊天室操作引发聊天室通知,这个扩展信息会置入消息的NIMMessage - messageExt - roomExt (messageExt需要转换成 NIMMessageChatroomExtension)。

  • 进入聊天室时设置。其他聊天室在线成员会收到该用户进入聊天室的通知消息,这个扩展信息会置入聊天室通知消息的NIMChatroomNotificationContent - notifyExt 里。

鉴权方式

聊天室通过loginAuthType字段支持三种鉴权方式。

typedef NS_ENUM(NSInteger, NIMChatroomLoginAuthType) {
    NIMChatroomLoginAuthTypeDefault = 0,
    NIMChatroomLoginAuthTypeDynamicToken = 1,
    NIMChatroomLoginAuthTypeThirdPart = 2,
};
  • 默认鉴权方式(静态 token 鉴权)

  • 动态token鉴权

    如果配置为动态token鉴权方式,则需要实现动态token回调。进入聊天室时,SDK通过此回调实时获取token。

  • NIMChatroomLoginAuthType原型

  • NIMProvideChatroomDynamicTokenHandler原型

/**
 * 聊天室动态token block
 */
typedef NSString*(^NIMProvideChatroomDynamicTokenHandler)(NSString * __nullable roomId, NSString * __nullable account);
  • 第三方回调鉴权

非独立模式

非独立模式较为简单,在IM处于登录状态时,无需设置NIMChatroomIndependentMode,直接调用进入聊天室方法即可。

独立模式

当选择以独立模式进入聊天室时,必须设置NIMChatroomIndependentMode的各项属性。

NIMChatroomIndependentMode 参数列表:

参数
类型
说明
username NSString 独立模式下的用户名,若设置为 nil ,SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatroomEnterRequest 必须设置昵称和头像信息
token NSString 独立模式下的 Token。 当用户名为空时,token 无效。
chatroomAppKey NSString 聊天室 AppKey, 可选填, 如果不填则使用云信IM AppKey。

进入聊天室后,可以通过如下接口获取进入该聊天室时所设置的模式:

@protocol  NIMChatroomManager <NSObject>
/**
*  获取聊天室登录使用的模式
*/
- (NSInteger)chatroomAuthMode:(NSString *)roomId;
  • 匿名模式与非匿名模式

独立模式下又可分为匿名模式与非匿名模式。匿名模式只能收消息,不能发消息。

NIMChatroomIndependentMode - username设置为nil时,则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatroomEnterRequest中必须设置昵称和头像信息。

  • 获取聊天室地址

独立模式由于不依赖IM连接,SDK无法自动获取聊天室服务器的地址,需要客户端向开发者应用服务器请求该地址,而应用服务器需要向网易云信服务器请求,然后将请求结果原路返回给客户端,即请求路径为:客户端 <-> 开发者应用服务器 <-> 网易云信服务器(API:请求聊天室地址)。

首先需要注册获取聊天室地址的回调方法:

@interface NIMChatroomIndependentMode : NSObject
/**
 *  注册获取聊天室地址的回调方法
 *
 *  @param handler 获取聊天室地址信息的方法
 *  @discussion 在进入聊天室和刷新聊天室 IP 时,SDK 都会主动调用这个回调方法,并传入相应的两个参数 `roomId` 和 `callback`。当前回调接口要求上层使用 `roomId` 走自己的网络请求获取对应聊天室地址并通过 callback 回调给 SDK。需要注意的时候无论请求成功,都需要通过 callback 进行回调,否则进入聊天室请求将会一直等待。同时此接口只需注册一次即可,多次注册将使用后者覆盖前者。
 */
+ (void)registerRequestChatroomAddressesHandler:(NIMRequestChatroomAddressesHandler)handler
@end

代码示例

 [NIMChatroomIndependentMode registerRequestChatroomAddressesHandler:^(NSString * _Nonnull roomId, NIMRequestChatroomAddressesCallback  _Nonnull callback) {
             [YourHTTPService request:roomId completion:^(NSError *error,NSArray *addresses)
             {
                 //无论请求是否成功,都需要进行回调
                 if(callback)
                 {
                     callback(error,addresses);
                 }
             }];
         }];

其中 YourHTTPService 为 App 的应用服务器接口,应用服务器可以调用云信服务端的请求聊天室地址 API 来获取具体的聊天室地址。

即针对独立模式进入聊天室,需要进行以下步骤:

  • 设置NIMChatroomIndependentMode,特别注意获取聊天室地址的回调方法。
  • 初始化NIMChatroomEnterRequest,并完成赋值。
  • 调用进入聊天室的方法。

聊天室多端登录

支持设置聊天室多端登录策略,即当同账号在不同客户端登录时,是否可以同时进入同一个聊天室。可以进入云信控制台选择应用 > IM专业版 > 功能配置 > 聊天室配置 > 聊天室多端登录配置进行设置。

  • 只允许一端登录,Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时,新设备会将旧设备踢下线。
  • 各端均可以同时登录在线。最多可支持10个设备同时在线,在设备数上限内,所有的新设备再次登录,均不会将在线的旧设备踢下线。

控制台修改多端互踢的逻辑之后,下次新的设备登录时才会基于新的多端互踢策略进行校验,已经建立连接的设备不会因为策略的修改被强制踢出。

如果某台设备重复登录同一个聊天室,后登录的会将前面的长连接断开,此时会再触发一次进入聊天室的抄送,但是不会触发退出聊天室的抄送。关于进出聊天室(eventType=9)的抄送请参见聊天室事件抄送

监听聊天室连接变化

进入聊天室会建立新的连接,不同的聊天室对应着不同的连接,开发者可以监听连接状态做一些业务处理。

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  监听聊天室连接状态变化
 *
 *  @param roomId 聊天室Id
 *  @param state  当前状态
 */
- (void)chatroom:(NSString *)roomId 
connectionStateChanged:(NIMChatroomConnectionState)state;
@end

NIMChatroomConnectionState 枚举列表

参数
说明
NIMChatroomConnectionStateEntering 0 正在进入聊天室
NIMChatroomConnectionStateEnterOK 1 进入聊天室成功
NIMChatroomConnectionStateEnterFailed 2 进入聊天室失败
NIMChatroomConnectionStateLoseConnection 3 和聊天室失去连接

当成功进入聊天室后,若再发生掉线问题时,SDK 将进行自动重连,无需开发者再次调用进入房间接口。

在重连时,可能遇到一些特殊网络错误(如聊天室用户被封禁,聊天室状态异常),会触发以下回调,开发者应该在这个回调中退出聊天室界面。

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  聊天室自动登录出错
 *
 *  @param roomId 聊天室Id
 *  @param error  自动登录出错原因
 */
- (void)chatroom:(NSString *)roomId 
 autoLoginFailed:(NSError *)error;
@end

监听被踢出

当用户被踢出聊天室或者聊天室关闭时,会触发被踢回调:

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  被踢回调
 *
 *  @param roomId   被踢的聊天室Id
 *  @param result   被踢的结果详情
 */
- (void)chatroomBeKicked:(NIMChatroomBeKickedResult *)result;
@end

被踢详情 NIMChatroomBeKickedResult

/**
 *  聊天室被踢结果
 */
@interface NIMChatroomBeKickedResult : NSObject

/**
 *  被踢的聊天室 Id
 */
@property (nonatomic, copy)      NSString    *roomId;

/**
 *  被踢的原因
 */
@property (nonatomic, assign)    NIMChatroomKickReason   reason;

/**
 *  被踢的扩展字段
 */
@property (nonatomic, copy)      NSString    *ext;

@end

NIMChatroomKickReason 枚举列表

参数
说明
NIMChatroomKickReasonInvalidRoom 1 聊天室已经解散
NIMChatroomKickReasonByManager 2 被聊天室管理员踢出
NIMChatroomKickReasonByConflictLogin 3 多端被踢
NIMChatroomKickReasonBlacklist 5 被拉黑

离开聊天室

离开聊天室时,会断开聊天室对应的连接,并不再收到关于此聊天室的任何消息。

@protocol NIMChatroomManager <NSObject>
/**
 *  离开聊天室
 *
 *  @param roomId     聊天室ID
 *  @param completion 离开聊天室的回调
 */
- (void)exitChatroom:(NSString *)roomId
          completion:(NIMChatroomHandler)completion;
@end

参数列表

参数
类型
说明
roomId NSString 聊天室 ID
completion NIMChatroomHandler 离开聊天室的回调

聊天室消息收发

聊天室消息收发接口与 IM 的消息收发接口统一,在发送消息时指定会话类型为聊天室即可。会话 id 即为聊天室 id。值得注意的是:针对聊天室消息,SDK不会持久化在本地。

部分重要参数如下:

参数
类型
说明
messageType NIMMessageType 消息类型 如果设置为自定义消息类型,建议将自定义消息的文本内容传入messageObject字段
session NIMSessionType 会话类型,包括单聊、群聊和聊天室等
notifyTargetTags NSString * 聊天室消息的目标表达式。目标表达式相关说明参见目标表达式
locationX NSNumber X坐标,用于聊天室空间消息
locationY NSNumber Y坐标,用于聊天室空间消息
locationZ NSNumber Z坐标,用于聊天室空间消息
toAccIds NSArray<NSString*> 消息接收者列表,用于聊天室定向消息,最多 100 个用户
  • 为保证用户体验(如避免服务器过载),目前针对消息接收,有两套流控机制。第一套针对普通消息,聊天室用户每秒至多可接收20条,超过部分会因为流控随机丢弃。第二套针对高优先级消息,每秒至多接收10条,超过部分无法保证不丢失。
  • 为避免丢失重要消息(通常为服务端消息),可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息,进而保证高优先级消息流控上限内(每秒10条)的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。

更新坐标

/**
 * 更新坐标
 * @param location 当前坐标和有效距离
 * @param completion 请求完成回调
 */
-(void)updateLocation:(nonnull NIMChatroomLocation *)location
        completion:(nullable NIMChatroomHandler)completion;
  • NIMChatroomLocation 参数列表
参数 类型 说明
roomId NSString 聊天室ID
locationX NSNumber X坐标
locationY NSNumber Y坐标
locationZ NSNumber Z坐标
distance NSNumber 距离

聊天室通知消息

在聊天室中进行部分操作会产生聊天室通知消息。目前当出现以下事件,会产生通知消息:

NIMChatroomEventType
说明
NIMChatroomEventTypeEnter = 301 成员进入聊天室
NIMChatroomEventTypeExit = 302 成员离开聊天室
NIMChatroomEventTypeAddBlack = 303 成员被拉黑
NIMChatroomEventTypeRemoveBlack = 304 成员被取消拉黑
NIMChatroomEventTypeAddMute = 305 成员被设置禁言
NIMChatroomEventTypeRemoveMute = 306 成员被取消禁言
NIMChatroomEventTypeAddManager = 307 设置为管理员
NIMChatroomEventTypeRemoveManager = 308 移除管理员
NIMChatroomEventTypeAddCommon = 309 设置为固定成员
NIMChatroomEventTypeRemoveCommon = 310 取消固定成员
NIMChatroomEventTypeClosed = 311 聊天室被关闭
NIMChatroomEventTypeInfoUpdated = 312 聊天室信息更新
NIMChatroomEventTypeKicked = 313 聊天室成员被踢
NIMChatroomEventTypeAddMuteTemporarily = 314 聊天室成员被临时禁言
NIMChatroomEventTypeRemoveMuteTemporarily = 315 聊天室成员被解除临时禁言
NIMChatroomEventTypeMemberUpdateInfo = 316 聊天室成员主动更新了聊天室的角色信息
NIMChatroomEventTypeQueueChange = 317 聊天室通用队列变更的通知
NIMChatroomEventTypeRoomMuted = 318 聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
NIMChatroomEventTypeRoomUnMuted = 319 聊天室解除禁言状态
NIMChatroomEventTypeQueueBatchChange = 320 聊天室通用队列批量变更的通知
NIMChatroomEventTypeRecall = 323 聊天室消息撤回
NIMChatroomEventTypeQueueBatchAdd = 324 批量添加聊天室队列元素

特别地,支持设置成员进出聊天室通知是否下发:

  • 应用级别:网易云信控制台 > 选择应用 > 聊天室用户进出消息系统下发 > 开启/关闭。
  • 单个聊天室:调用服务端API「关闭指定聊天室进出通知」。
  • 如果希望查询聊天室消息历史时,也不要包含聊天室用户进出消息,请联系商务顾问申请关闭「聊天室用户进出消息历史存储」。

所有的聊天室通知都以消息 NIMMessage 的形式封装。聊天室通知的解析如下:

  1. 判断消息是否为通知消息。

    • 判断 NIMMessage - messageType 字段是否为 NIMMessageTypeNotification
  2. 再判断是否为聊天室通知消息。

    • NIMMessage - messageObject 强类型转换为 NIMNotificationObject
    • 判断转换后的 NIMNotificationObject - notificationType 字段是否为 NIMNotificationTypeChatroom
  3. 解析具体内容。

    • NIMNotificationObject - content 字段强类型转换为 NIMChatroomNotificationContent

聊天室通知内容 NIMChatroomNotificationContent 的字段说明:

  • eventType : 聊天室通知事件类型,表示具体属于哪一种聊天室通知,通知种类由 NIMChatroomEventType 枚举定义。
  • source : 通知的操作者,表示谁触发了这个通知,被封装为NIMChatroomNotificationMember 类型。
  • targets : 通知的被操作者,表示这个通知影响的用户,被封装为 NSArray 类型, NSArray 中每个元素被封装成 NIMChatroomNotificationMember 类型。
  • notifyExt : 通知的扩展字段,这个扩展字段是由每个触发通知的操作接口定义的。如进入聊天室时设置的NIMChatroomEnterRequest - roomNotifyExt
  • ext : 目前只有 临时禁言/队列操作 事件才有,记录禁言时长信息、队列操作具体信息等。
  • revokedMessageId : 被撤回消息的ID
  • revokedMessageTime : 被撤回消息的时间

下面针对聊天室队列元素变更通知消息的解析进行示例:

NIMChatroomNotificationContenteventType 事件中,有两种事件属于聊天室变更事件分别为NIMChatroomEventTypeQueueChangeNIMChatroomEventTypeQueueBatchChange

消息解析示例:

- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages
{
    for (NIMMessage *message in messages)
    {
        if (message.messageType == NIMMessageTypeNotification)
        {
            if (notification.notificationType == NIMNotificationTypeChatroom)
            {
                NIMChatroomNotificationContent *content = (NIMChatroomNotificationContent *)notification.content;
                NSDictionary *info = content.ext;
                if (content.eventType == NIMChatroomEventTypeQueueChange)
                {
                    //change type
                    //NIMChatroomQueueChangeTypeOffer, NIMChatroomQueueChangeTypePoll, NIMChatroomQueueChangeTypeDrop,NIMChatroomQueueChangeTypeUpdate
                    NIMChatroomQueueChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    //key
                    NSString *key = [info objectForKey:NIMChatroomEventInfoQueueChangeItemKey];
                    //value
                    NSString *value = [info objectForKey:NIMChatroomEventInfoQueueChangeItemValueKey];
                    //deal with key and value
                }
                if (content.eventType == NIMChatroomEventTypeQueueBatchChange)
                {
                    //change type
                    //NIMChatroomQueueBatchChangeTypePartClear
                    NIMChatroomQueueBatchChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    NSDictionary *batch = [info objectForKey:NIMChatroomEventInfoQueueChangeItemsKey];
                    for (NSString *key in batch)
                    {
                        NSString *value = [batch objectForKey:key];
                        //deal with key and value
                    }
                }
            }
        }
    }
}
  • 关于例子中在ext中解析出来的changeType

NIMChatroomNotificationContenteventTypeNIMChatroomEventTypeQueueChange, 则changeTypeNIMChatroomQueueChangeType:

  • 无效或未知变更类型 NIMChatroomQueueChangeTypeInvalid
  • 新增元素 NIMChatroomQueueChangeTypeOffer
  • 取出元素 NIMChatroomQueueChangeTypePoll
  • 清空元素 NIMChatroomQueueChangeTypeDrop
  • 更新元素 NIMChatroomQueueChangeTypeUpdate

NIMChatroomNotificationContenteventTypeNIMChatroomEventTypeQueueBatchChange, 则changeTypeNIMChatroomQueueBatchChangeType:

  • 无效或未知变更类型 NIMChatroomQueueBatchChangeTypeInvalid
  • 部分批量清理(发生在提交元素的用户掉线时,清理这个用户对应的key) NIMChatroomQueueBatchChangeTypePartClear

查询云端历史消息

聊天室没有离线消息和漫游消息。可以通过下面的接口查询聊天室消息历史。服务器只保存最近10天的聊天室消息记录。但是10天之前发送的文件(例如:图片、音频、视频等),其url链接地址仍然是有效的(不过开发者需要自行保存这些url,因为无法通过已过期的消息来查询这些文件url)。如需延长「聊天室历史消息天数」,请联系商务顾问。

@protocol NIMChatroomManager <NSObject>
/**
 *  查询服务器保存的聊天室消息记录
 * 
 *  @param roomId  聊天室ID
 *  @param option  查询选项
 *  @param result   完成回调
 */
- (void)fetchMessageHistory:(NSString *)roomId
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(NIMFetchChatroomHistoryBlock)completion;
@end                     

NIMHistoryMessageSearchOption 参数列表 (部分字段对聊天室消息搜索选项无效,已过滤)

参数
类型
说明
startTime NSTimeInterval 检索消息起始时间,需要检索的起始时间,没有则传入0。即以该时间为起点,往前或往后查询。
limit NSUInteger 检索条数,最大限制 100 条
order NIMMessageSearchOrder 检索顺序
messageTypes NSArray<NSNumber *> 查询的消息类型,默认为 nil ,搜索全类型。

根据标签查询历史消息

根据标签(Tags)在云端查询聊天室的历史消息。

以 fromTime 和 toTime(单位秒)为时间戳,选择查询方向,指定一种或多种标签和消息类型,往前或者往后拉取 limit 条消息。

/**
 * 通过标签查询消息
 * @param param 查询参数
 * @param completion 完成回调
 */
- (void)getMessagesByTags:(NIMGetMessagesByTagsParam *)param
              completion:(nullable NIMGetMessagesByTagsHandler)completion;

NIMGetMessagesByTagsParam 参数列表

参数
类型
说明
roomId NSInteger 聊天室 ID(必填)
tags NSArray<NSString *> 标签列表,支持传入多个标签同时查询(必填)
messageTypes NSArray<NSNumber *> 消息类型列表,查询指定消息类型的消息,默认查询全部消息类型
fromTime NSNumber * 起始时间,单位秒。被转换为NSTimeInterval类型使用
toTime NSNumber * 结束时间,单位秒。被转换为NSTimeInterval类型使用
limit NSNumber * 可查询的最大消息数量。被转换为NSInteger类型使用
reverse NSNumber * 查询方向。被转换为BOOL类型使用

示例代码如下:

[[NIMSDK sharedSDK].chatroomManager getMessagesByTags:param completion:^(NSError * __nullable error,NSArray<NIMMessage *> * __nullable messages) {
    if (error) {
        // 获取消息失败
    } else {
        // 获取消息成功
    }
}];

聊天室信息管理

获取聊天室信息

此接口可以远程获取聊天室信息,NIM SDK 不会缓存聊天室信息,开发者需要根据业务自己做好缓存。

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室信息
 *
 *  @param roomId     聊天室ID
 *  @param completion 获取聊天室信息的回调
 *  @discussion 只有已进入聊天室才能够获取对应的聊天室信息
 */
- (void)fetchChatroomInfo:(NSString *)roomId
               completion:(NIMChatroomInfoHandler)completion;
@end               

参数列表

参数
类型
说明
roomId NSString 聊天室 ID
completion NIMChatroomInfoHandler 离开聊天室的回调

修改聊天室信息

@protocol NIMChatroomManager <NSObject>
/**
 *  修改聊天室信息
 *
 *  @param request    聊天室修改请求
 *  @param completion 修改后完成的回调
 */
- (void)updateChatroomInfo:(NIMChatroomUpdateRequest *)request
                completion:(nullable NIMChatroomHandler)completion;
@end  

NIMChatroomUpdateRequest 参数列表

参数
类型
说明
roomId NSString 聊天室ID
updateInfo NSDictionary 修改信息字段,修改传入的数据键值对是 {@(NIMChatroomUpdateTag) : NSString 或 NSNumber},无效数据将被过滤
needNotify BOOL 是否需要通知, 默认NO
notifyExt NSString 放到事件通知里的扩展字段
antispamBusinessId NSString 某些资料内容另外的反垃圾的业务ID

聊天室成员管理

聊天室成员概述

关于聊天室成员:

  • 聊天室成员包括固定成员和非固定成员(临时成员/游客)。固定成员上限是1000个。
  • 固定成员包括四种类型:创建者、管理员、普通用户、受限用户。受限用户又包括:黑名单用户和永久禁言用户。
  • 除了创建者,其他成员刚加入时,默认都是游客。
  • 如果游客被设置为管理员,再被取消管理员,则变为普通用户(而不是游客)。
  • 要将管理员变成普通用户,直接取消其管理员权限即可。不能直接将管理员设置为普通成员。
  • 只有创建者可以对管理员进行操作,管理员不能对创建者和其他管理员进行操作。
  • 普通用户被取消身份后变为游客。
  • 游客被设置为黑名单用户后变为固定成员(同时会被服务器断开连接并且无法进入聊天室,除非被解除黑名单)。解除黑名单后变为游客。
  • 永久禁言后,身份变为固定成员。解除永久禁言后,身份变为游客。解除永久禁言后,不影响临时禁言的到期时间。
  • 临时禁言的设置和解除不会改变成员的身份。如果重复设置临时禁言,则后一次设置会覆盖前一次设置的到期时间(不会累积)。
  • 游客只有在线时才属于聊天室的非固定成员;游客进入聊天室又退出后,不属于聊天室的任何成员(和聊天室没有任何关系)。

聊天室成员原型:

/**
 *  聊天室用户
 */
@interface NIMChatroomMember : NSObject

/**
 *  用户ID
 */
@property (nullable,nonatomic,copy)   NSString *userId;

/**
 *  聊天室内的昵称字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomNickname;

/**
 *  聊天室内的头像字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomAvatar;

/**
 *  用户在聊天室内的头像缩略图
 *  @discussion 仅适用于使用云信上传服务进行上传的资源,否则无效。
 */

@property (nullable,nonatomic,copy,readonly)  NSString    *roomAvatarThumbnail;

/**
 *  聊天室内预留给开发者的扩展字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomExt;

/**
 *  用户类型
 */
@property (nonatomic,assign) NIMChatroomMemberType type;

/**
 *  是否被禁言
 */
@property (nonatomic,assign) BOOL isMuted;

/**
 *  是否被临时禁言
 *  @discussion 临时禁言和禁言属性无相关性
 */
@property (nonatomic,assign) BOOL isTempMuted;

/**
 *  临时禁言剩余时长
 */
@property (nonatomic,assign) unsigned long long tempMuteDuration;

/**
 *  是否被拉黑
 */
@property (nonatomic,assign) BOOL isInBlackList;

/**
 *  是否在线, 仅特殊成员才可能离线, 对游客用户而言只能是在线
 */
@property (nonatomic,assign) BOOL isOnline;

/**
 *  进入聊天室的时间点
 */
@property (nonatomic,assign) NSTimeInterval enterTimeInterval;

/**
 *  聊天室成员的tags
 */
@property (nullable,nonatomic,copy)   NSString *tags;

/**
 *  聊天室成员的notifyTargetTags
 */
@property (nullable,nonatomic,copy)   NSString *notifyTargetTags;

@end

获取聊天室成员

此接口可以远程获取聊天室成员列表,NIM SDK 不会缓存聊天室成员列表,开发者需要根据业务自己做好缓存。

分页获取聊天室成员

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室成员
 *
 *  @param request    获取成员请求
 *  @param completion 请求完成回调
 */
- (void)fetchChatroomMembers:(NIMChatroomMemberRequest *)request
                  completion:(NIMChatroomMembersHandler)completion;
@end                  

NIMChatroomMemberRequest 参数列表

参数
类型
说明
roomId NSString 聊天室 ID
type NIMChatroomFetchMemberType 聊天室成员类型.
lastMember NIMChatroomMember 最后一位成员锚点,不包括此成员。填nil会使用当前服务器最新时间开始查询,即第一页。
limit NSUInteger 获取聊天室成员个数

NIMChatroomFetchMemberType 类型

参数
说明
NIMChatroomFetchMemberTypeRegular 聊天室固定成员
NIMChatroomFetchMemberTypeTemp 聊天室临时成员
NIMChatroomFetchMemberTypeRegularOnline 聊天室在线的固定成员
NIMChatroomFetchMemberTypeUnRegularReversedOrder 聊天室非固定成员(反向查询)

获取指定聊天室成员

@protocol NIMChatroomManager <NSObject>
/**
 *  根据用户ID获取聊天室成员信息
 *
 *  @param request    获取成员请求
 *  @param completion 请求完成回调
 */
- (void)fetchChatroomMembersByIds:(NIMChatroomMembersByIdsRequest *)request
                    completion:(NIMChatroomMembersHandler)completion;
@end                    

NIMChatroomMembersByIdsRequest 参数列表

参数
类型
说明
roomId NSString 聊天室 ID
userIds NSArray<NSString *> 用户ID列表,最多20个

修改自身信息

@protocol NIMChatroomManager <NSObject>
/**
* 修改自身聊天室内信息
*/
- (void)updateMyChatroomMemberInfo:(NIMChatroomMemberInfoUpdateRequest *)request
                        completion:(nullable NIMChatroomHandler)completion;
@end

NIMChatroomMemberInfoUpdateRequest参数

/**
 *  聊天室成员信息修改请求
 */
@interface NIMChatroomMemberInfoUpdateRequest : NSObject

/**
 *  聊天室ID
 */
@property (nonatomic,copy) NSString *roomId;

/**
 *  需要更新的信息,修改传入的数据键值对是 {@(NIMChatroomMemberInfoUpdateTag) : NSString},无效数据将被过滤
 */
@property (nonatomic,copy) NSDictionary *updateInfo;

/**
 *  是否需要通知
 */
@property (nonatomic,assign) BOOL needNotify;

/**
 *  操作通知事件扩展
 */
@property (nullable,nonatomic,copy) NSString *notifyExt;

/**
 *  更新的信息是否需要在服务器做持久化,只对固定成员生效,默认为 NO
 */
@property (nonatomic,assign) BOOL needSave;

/**
 * 对某些资料内容另外的反垃圾的业务ID
 */
@property (nonatomic,strong)    NSString *antispamBusinessId;

@end

示例:

NIMChatroomMemberInfoUpdateRequest *request = [[NIMChatroomMemberInfoUpdateRequest alloc] init];
request.roomId = @"123";
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"zhangsan" forKey:@(NIMChatroomMemberInfoUpdateTagNick)];
request.updateInfo = dic;
[[NIMSDK sharedSDK].chatroomManager updateMyChatroomMemberInfo:request 
                                                    completion:^(NSError * _Nullable error) { }];

调用完这个接口后,开发者应该自己修改内存缓存的 聊天室成员 对象。

添加/移除管理员

@protocol NIMChatroomManager <NSObject>
/**
 *  添加/移除聊天室管理员
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)markMemberManager:(NIMChatroomMemberUpdateRequest *)request
              completion:(NIMChatroomHandler)completion;
@end              

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除普通成员

@protocol NIMChatroomManager <NSObject>
/**
 *  添加/移除聊天室普通成员
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)markNormalMember:(NIMChatroomMemberUpdateRequest *)request
            completion:(NIMChatroomHandler)completion;
@end            

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除黑名单用户

@protocol NIMChatroomManager <NSObject>
/**
 *  更新用户聊天室黑名单状态
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)updateMemberBlack:(NIMChatroomMemberUpdateRequest *)request
              completion:(NIMChatroomHandler)completion;
@end              

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除禁言用户

@protocol NIMChatroomManager <NSObject>
/**
 *  更新用户聊天室静言状态
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)updateMemberMute:(NIMChatroomMemberUpdateRequest *)request
            completion:(NIMChatroomHandler)completion;
@end            

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

踢出成员

创建者或管理员可以将权限比自己低的用户踢出聊天室。

@protocol NIMChatroomManager <NSObject>
/**
 *  将特定成员踢出聊天室
 *
 *  @param request    踢出请求
 *  @param completion 请求回调
 */
- (void)kickMember:(NIMChatroomMemberKickRequest *)request
        completion:(NIMChatroomHandler)completion;
@end        

NIMChatroomMemberKickRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
userId NSString 用户 ID ,仅管理员可以踢人;如userId是管理员仅创建者可以踢
notifyExt NSString 被踢通知扩展字段

临时禁言成员

@protocol NIMChatroomManager <NSObject>

/**
 *  更新用户聊天室临时禁言状态
 *
 *  @param request    更新请求
 *  @param duration   临时禁言时长,单位为秒
 *  @param completion 请求回调
 */
- (void)updateMemberTempMute:(NIMChatroomMemberUpdateRequest *)request
                    duration:(unsigned long long)duration
                  completion:(nullable NIMChatroomHandler)completion;
                
@end

聊天室队列

聊天室提供队列服务,可结合互动直播连麦场景中的麦位管理使用。权限由 NIMChatroom - queueModificationLevel 决定,可以通过updateChatroomInfo进行修改。默认情况下,所有用户都可以调用接口修改队列内容。

获取聊天室队列

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室队列
 *
 *  @param roomId     聊天室ID
 *  @param completion 请求回调
 */
- (void)fetchChatroomQueue:(NSString *)roomId
                completion:(nullable NIMChatroomQueueInfoHandler)completion;
@end                      

示例

NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager fetchChatroomQueue:roomId 
                                            completion:^(NSError * _Nullable error, NSArray<NSDictionary<NSString *,NSString *> *> * _Nullable info) {
    if (!error)
    {
        //deal with info
    }
    else
    {
        //deal with error
    }
}];

加入或者更新队列元素

若该元素由用户A添加,之后再由用户B更新,则该元素的所有者为用户B。

@protocol NIMChatroomManager <NSObject>
/**
 *  加入或者更新聊天室通用队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定。
 *  
 *  @param request    聊天室队列请求
 *  @param completion 请求回调
 */
- (void)updateChatroomQueueObject:(NIMChatroomQueueUpdateRequest *)request
                       completion:(nullable NIMChatroomHandler)completion;
@end                      

NIMChatroomQueueUpdateRequest 参数列表

参数
类型
说明
roomId NSString 聊天室 ID
key NSString 更新元素的 Key 值,如果 key 在队列中存在则更新,不存在则放到队列尾部 ,长度限制为 32 字节
value NSString 更新元素的 Value 值,长度限制为 4096 字节
transient BOOL 当提交这个新元素到聊天室队列的用户从聊天室掉线或退出的时候,是否需要删除这个元素,默认为 false 不删除。当设置为 YES 时,掉线或退出后,聊天室会发出队列批量元素变更通知 NIMChatroomEventTypeQueueBatchChange
elementAccid NSString 队列元素所属账号,默认不传表示队列元素属于当前操作人,管理员可以指定队列元素归属于其他合法账号

示例

NIMChatroomQueueUpdateRequest *request = [[NIMChatroomQueueUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.key    = @"key";
request.value  = @"value";
request.transient = YES;
req.element_accid_ = UTF8(request.elementAccid);
[[NIMSDK sharedSDK].chatroomManager updateChatroomQueueObject:request 
                                                   completion:^(NSError * _Nullable error) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];

批量更新队列元素

若该元素由用户A添加,之后再由用户B更新,则该元素的所有者为用户B。

@protocol NIMChatroomManager <NSObject>
/**
 *  批量更新聊天室通用队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param request    聊天室队列批量请求
 *  @param completion 请求回调
 */
- (void)batchUpdateChatroomQueueObject:(NIMChatroomQueueBatchUpdateRequest *)request
                       completion:(nullable NIMChatroomQueueBatchUpdateHandler)completion;
@end                      

NIMChatroomQueueBatchUpdateRequest 参数列表

参数
类型
说明
roomId NSString 聊天室 ID
elements NSDictionary 批量更新元素的key-value对,key/value分别是elementKey和elementValue(elementKey限制128字节,elementValue限制4096字节),一次最多更新100个
needNotify BOOL 是否需要发送广播通知
notifyExt NSString 通知中的自定义字段,长度限制 2048 字节

示例

NIMChatroomQueueBatchUpdateRequest *request = [[NIMChatroomQueueBatchUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.needNotify = YES;
request.notifyExt = @"你收到一个通知";
request.elements = dict;
[[NIMSDK sharedSDK].chatroomManager batchUpdateChatroomQueueObject:request completion:^(NSError * _Nullable error, NSArray<NSString *> * _Nullable elements) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];

移除指定队列元素

@protocol NIMChatroomManager <NSObject>
/**
 *  移除聊天室队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param request    拉取请求
 *  @param completion 请求回调
 */
- (void)removeChatroomQueueObject:(NIMChatroomQueueRemoveRequest *)request
                       completion:(nullable NIMChatroomQueueRemoveHandler)completion;
@end                      

NIMChatroomQueueRemoveRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
key NSString 指定的元素的Key值,如果是第一个元素,则传空

示例

NIMChatroomQueueRemoveRequest *request = [[NIMChatroomQueueRemoveRequest alloc] init];
request.roomId = @"your_room_id";
request.key    = @"key";
[[NIMSDK sharedSDK].chatroomManager removeChatroomQueueObject:request completion:^(NSError * _Nullable error, NSDictionary<NSString *,NSString *> * _Nullable element) {
    if (!error)
    {
        //deal with removed element
    }
    else
    {
        //deal with error
    }
}];

清空队列

@protocol NIMChatroomManager <NSObject>
/**
 *  删除聊天室队列,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param roomId     聊天室ID
 *  @param completion 请求回调
 */
- (void)dropChatroomQueue:(NSString *)roomId
               completion:(nullable NIMChatroomHandler)completion;
@end                      

示例

NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager dropChatroomQueue:roomId completion:^(NSError * _Nullable error) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];

聊天室标签

监听聊天室标签变更

监听聊天室标签变更事件后,当聊天室标签别修改后,会受到回调,包含变更标签的聊天室 ID 和变更后的标签信息。

/**
 * 聊天室标签修改通知
 * @param event 修改通知
 */
- (void)tagsUpdate:(NIMChatroomTagsUpdateEvent *)event;

更新标签

支持随时更新自己的标签

/**
 * 更新标签
 * @param tags 标签
 * @param completion 请求完成回调
 */
-(void)updateTags:(nonnull NIMChatroomTagsUpdate *)tags
           completion:(nullable NIMChatroomHandler)completion;
  • NIMChatroomTagsUpdate 参数列表
参数
类型
说明
roomId NSString 聊天室ID
tags NSArray 标签,可以设置多个,如果不传,则会删掉老的标签
notifyTargetTags NSString 更新标签的通知的目标标签,是一个标签表达式,同时也会改变该连接掉线时的通知对象,见TagCalculator和TagPattern,如果不传,则会删掉老的notifyTargetTags
needNotify BOOL 是否需要通知,填true则会产生一条通知,类型为325
ext NSString 通知扩展字段
此文档是否对你有帮助?
有帮助
去反馈
  • 功能概述
  • 进入聊天室
  • 鉴权方式
  • 非独立模式
  • 独立模式
  • 聊天室多端登录
  • 监听聊天室连接变化
  • 监听被踢出
  • 离开聊天室
  • 聊天室消息收发
  • 更新坐标
  • 聊天室通知消息
  • 查询云端历史消息
  • 根据标签查询历史消息
  • 聊天室信息管理
  • 获取聊天室信息
  • 修改聊天室信息
  • 聊天室成员管理
  • 聊天室成员概述
  • 获取聊天室成员
  • 分页获取聊天室成员
  • 获取指定聊天室成员
  • 修改自身信息
  • 添加/移除管理员
  • 添加/移除普通成员
  • 添加/移除黑名单用户
  • 添加/移除禁言用户
  • 踢出成员
  • 临时禁言成员
  • 聊天室队列
  • 获取聊天室队列
  • 加入或者更新队列元素
  • 批量更新队列元素
  • 移除指定队列元素
  • 清空队列
  • 聊天室标签
  • 监听聊天室标签变更
  • 更新标签