集成开发

聊天室管理

更新时间： 2024/03/07 11:11:47

聊天室

功能概述

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

聊天室原型 NIMChatroomInfo：

类型	属性	说明
String	roomId	获取聊天室 id
String?	announcement	获取聊天室公告
String?	broadcastUrl	获取聊天室直播地址
String?	creator	获取聊天室创建者帐号
Map<String, dynamic>?	extension	获取聊天室扩展字段
String?	name	获取聊天室名称
int	onlineUserCount	获取当前在线用户数量
NIMChatroomQueueModificationLevel	queueModificationLevel	获取队列权限配置
bool	mute	获取当前聊天室禁言状态
bool	validFlag	获取聊天室有效标记

进入聊天室

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

进入聊天室可以有两种方式：以独立模式进入聊天室和非独立模式进入聊天室。
独立模式是指在 IM 处于未登录的情况下，进入聊天室的方式，针对只需要聊天室功能的业务场景。
非独立模式是指先完成 IM 登录，再进入聊天室的方式，针对需要 IM 和聊天室功能的业务场景。

dartclass ChatroomService {
  /// 加入聊天室
  Future<NIMResult<NIMChatroomEnterResult>> enterChatroom(
      NIMChatRoomEnterRequest request);
}

NIMChatRoomEnterRequest 部分参数说明：

类型	属性	说明
String	roomId	聊天室 ID
String?	avatar	设置聊天室展示的头像
Map<String, dynamic>?	extension	设置进入聊天室后展示用户信息的扩展字段，长度限制 4k。设置后在获取聊天室成员信息 NIMChatroomMember 时可以查询到此扩展字段；此外，在收到聊天室消息时，可以从 NIMChatroomMessage#extension#senderExtension 中获取消息发送者的用户信息扩展字段。若没有设置，则这个字段为 null。
String?	nickname	设置聊天室展示的昵称(可选字段), 如果不填则直接使用 UserInfo 中的昵称
Map<String, dynamic>?	notifyExtension	设置聊天室通知消息扩展字段，长度限制 2k。设置后，在收到聊天室通知消息的 NIMChatroomNotificationAttachment#extension 中可以获取到此扩展字段。
int	retryCount	重试加入聊天室的次数（Windows 和 macOS 暂不支持）

非独立模式

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

示例

dart    NimCore.instance.chatroomService.enterChatroom(
      NIMChatRoomEnterRequest(
        roomId: '123456',
        nickname: 'nickname',
        retryCount: 3,
      ),
    ).then((result) {
      if (result.isSuccess) {
        /// 加入聊天室成功
      } else {
        /// 加入聊天室失败
      }
    });

独立模式

当选择以独立模式进入聊天室时，必须设置NIMChatRoomEnterRequest.independentModeConfig字段的各项属性，它的类型为 NIMChatRoomIndependentModeConfig。

NIMChatRoomIndependentModeConfig 参数列表：

参数	类型	说明
appKey	String	独立模式的 AppKey
linkAddresses	List<String>	聊天室服务器的地址
account	String？	独立模式下的用户名，若设置为 null ，SDK 将使用自动生成的匿名账号进行登录。在匿名模式下，NIMChatRoomEnterRequest 必须设置昵称和头像信息
token	String？	独立模式下的 Token。当用户名为空时，token 无效。

匿名模式与非匿名模式

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

当NIMChatRoomIndependentModeConfig.account设置为 null 时，则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下，NIMChatRoomEnterRequest中必须设置昵称和头像信息。

获取聊天室地址

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

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

获取聊天室地址
设置NIMChatRoomIndependentModeConfig
初始化NIMChatRoomEnterRequest，并赋值independentModeConfig字段。
调用进入聊天室的方法。
示例(以匿名模式加入独立聊天室)

dart    NimCore.instance.chatroomService.enterChatroom(
      NIMChatRoomEnterRequest(
        roomId: '123456',
        nickname: 'nickname',
        avatar: 'http://avatar_url.png'
        retryCount: 3,
        independentModeConfig: NIMChatRoomIndependentModeConfig(
          appKey: 'independent_mode_appkey',
          linkAddresses: ['chatroom_link_address'],
        ),
      ),
    ).then((result) {
      if (result.isSuccess) {
        /// 加入独立聊天室成功
      } else {
        /// 加入独立聊天室失败
      }
    });

聊天室多端登录

支持设置聊天室多端登录策略，即当同账号在不同客户端登录时，是否可以同时进入同一个聊天室。可以进入云信控制台进行设置：

只允许一端登录
各端均可以同时登录在线

监听聊天室连接变化

进入聊天室成功后，SDK 会负责维护与服务器的长连接以及断线重连等工作。当用户在线状态发生改变时，会发出通知。登录过程也有状态回调。此外，网络连接上之后，SDK 会负责聊天室的自动登录。

API 原型

dartclass ChatroomService {
  /// 聊天室事件流
  ///
  /// [NIMChatroomStatusEvent] 聊天室状态事件
  ///
  /// [NIMChatroomKickOutEvent] 聊天室离开事件
  Stream<NIMChatroomEvent> get onEventNotified;
}

onEventNotified 会通知两类事件，包括连接状态事件 NIMChatroomStatusEvent 和离开事件 NIMChatroomKickOutEvent

NIMChatroomStatusEvent 类型说明

属性	说明
roomId	聊天室 ID
status	状态码，参考 NIMChatroomStatus
code	错误码，参考 NIMChatroomErrors
错误码	说明
:-----	:-----------------------
414	参数错误
404	聊天室不存在
403	无权限
500	服务器内部错误
13001	IM 主连接状态异常
13002	聊天室状态异常
13003	黑名单用户禁止进入聊天室

示例

dart
    final subscription = NimCore.instance.chatroomService
        .onEventNotified.listen((event) {
      if (event is NIMChatroomStatusEvent) {
        /// 连接状态事件通知
      }
    });

    /// 不再使用时，需要取消监听
    /// subscription.cancel();

监听被踢出

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

注意：收到被踢出通知后，不需要再调用退出聊天室接口，SDK 会负责聊天室的退出工作。可以在踢出通知中做相关缓存的清理工作和界面操作。

API 原型

dartclass ChatroomService {
  /// 聊天室事件流
  ///
  /// [NIMChatroomStatusEvent] 聊天室状态事件
  ///
  /// [NIMChatroomKickOutEvent] 聊天室离开事件
  Stream<NIMChatroomEvent> get onEventNotified;
}

NIMChatroomKickOutEvent 类型说明

属性	说明
roomId	聊天室 ID
reason	原因，参考 NIMChatroomKickOutReason
extension	扩展字段
NIMChatroomKickOutReason 枚举	说明
:----------------------------	:---------------
blacklisted	被拉黑了
dismissed	聊天室已经被关闭
byConflictLogin	被其他端踢出
byManager	被管理员踢出
unknown	未知（出错情况）

示例

dart
    final subscription = NimCore.instance.chatroomService
        .onEventNotified.listen((event) {
      if (event is NIMChatroomKickOutEvent) {
        /// 离开事件通知
      }
    });

    /// 不再使用时，需要取消监听
    /// subscription.cancel();

离开聊天室

离开聊天室，会断开聊天室对应的链接，并不再收到该聊天室的任何消息。如果用户要离开聊天室，可以手动调用离开聊天室接口，该接口没有回调。

###离开单个聊天室

API 原型

dartclass ChatroomService {
  /// 退出聊天室
  Future<NIMResult<void>> exitChatroom(String roomId);
}

示例

dartNimCore.instance.chatroomService.exitChatroom(roomId);

聊天室消息收发

聊天室消息 NIMChatroomMessage 继承自 NIMMessage。新增了以下方法：

类型	属性	说明
NIMChatroomMessageExtension	extension	获取聊天室消息扩展属性
bool	isHighPriorityMessage	是否是高优先级消息
bool	enableHistory	该消息是否要保存到服务器

为保证用户体验（如避免服务器过载），目前针对消息接收，有两套流控机制。第一套针对普通消息，聊天室用户每秒至多可接收20条，超过部分会因为流控随机丢弃。第二套针对高优先级消息，每秒至多接收10条，超过部分无法保证不丢失。
为避免丢失重要消息（通常为服务端消息），可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息，进而保证高优先级消息流控上限内（每秒10条）的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。

发送聊天室消息

先通过 ChatroomMessageBuilder 提供的接口创建消息对象 NIMChatroomMessage，然后调用 ChatroomService 的 sendMessage 接口发送出去即可。注意，创建消息对象的接口也为异步。

1秒内默认最多可调用该接口100次。如需上调上限，请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

ChatRoomMessageBuilder 接口说明

返回值	ChatRoomMessageBuilder 接口	说明
Future<NIMResult<NIMChatroomMessage>>	createChatroomAudioMessage({required String roomId,required String filePath,required int duration,NIMNosScene nosScene = NIMNosScenes.defaultIm,})	创建一条音频消息（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatroomCustomMessage({required String roomId,NIMMessageAttachment? attachment,})	创建自定义消息
Future<NIMResult<NIMChatroomMessage>>	createChatroomFileMessage({required String roomId,required String filePath,required String displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,})	创建一条文件消息（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatroomImageMessage({required String roomId,required String filePath,String? displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,})	创建一条图片消息（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatroomLocationMessage({required String roomId,required double latitude,required double longitude,required String address,})	创建一条地理位置信息（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatroomTextMessage({required String roomId,required String text,})	创建普通文本消息
Future<NIMResult<NIMChatroomMessage>>	createChatroomVideoMessage({required String roomId,required String filePath,required int duration,required int width,required int height,String? displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,})	创建一条视频消息（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatRoomVideoMessage(String roomId, File file, long duration, int width, int height, String displayName, String nosTokenSceneKey)	创建一条视频消息并指定文件资源场景（Windows 和 macOS 暂不支持）
Future<NIMResult<NIMChatroomMessage>>	createChatroomTipMessage({required String roomId,})	创建一条提醒消息（Windows 和 macOS 暂不支持）

nosTokenSceneKey 详见文件资源场景。

下面以文本消息发送为例，其它类型的消息发送方式与 IM 单聊群聊类似。

API 原型

dartclass ChatroomMessageBuilder {
  /// 创建文本消息
  static Future<NIMResult<NIMChatroomMessage>> createChatroomTextMessage({
    required String roomId,
    required String text,
  }) async { ... }
}

class ChatroomService {
    /// 发送聊天室消息
    ///
    /// 聊天室消息通过 [ChatroomMessageBuilder] 进行创建
    ///
    /// [resend] 如果是发送失败后重发，标记为true，否则填false，默认为
    Future<NIMResult<NIMChatroomMessage>> sendChatroomMessage(
      NIMChatroomMessage message,
      [bool resend = false]) async {
    ...
  }
}

示例

dart    ChatroomMessageBuilder.createChatroomTextMessage(
        roomId: '123456',
        text: 'Hello World!',
    ).then<NIMResult>((result) {
        if (result.isSuccess) {
            return chatroomService.sendChatroomMessage(result.data!);
        } else {
            return result;
        }
    }).then((value) {
        print('ChatroomService##send message: ${value.code} ${value.errorDetails}');
    });

特殊错误码

错误码	说明
13004	在禁言列表中，不允许发言
13006	聊天室处于整体禁言状态,只有管理员能发言

发送消息配置选项

发送聊天室消息时，可以设置配置选项 enableHistory ，主要用于设置是否存入云端历史记录。

NIMChatroomMessage 属性	说明
enableHistory	该消息是否要保存到服务器，如果为 true，通过 ChatroomService#pullMessageHistory 拉取的结果将包含该条消息。默认为 true。

示例

dartChatroomMessageBuilder.createChatroomTextMessage(
        roomId: '123456',
        text: 'Hello World!',
    ).then<NIMResult>((result) {
        if (result.isSuccess) {
            result.data!.enableHistory = false;
            return chatroomService.sendChatroomMessage(result.data!);
        } else {
            return result;
        }
    }).then((value) {
        print('ChatroomService##send message: ${value.code} ${value.errorDetails}');
    });

接收聊天室消息

通过监听消息事件，在有新消息到达时，就可以接收到通知。

API 原型

dartclass ChatroomService {
    /// 聊天室消息
    ///
    Stream<List<NIMChatroomMessage>> get onMessageReceived;
}

示例

dartfinal subsription = NimCore.instance.chatroomService.onMessageReceived.listen((messages) {
      messages.forEach((message) {
        print(
            'ChatroomService##on message received: ${message.fromAccount} ${message.fromNickname} '
            '\'${message.content}\'');
      }
});

/// 不再监听时需要移除监听器
/// subscription.cancel();

附件的下载，请使用ChatroomService的downloadAttachment方法进行下载。
监听消息状态变化，请使用ChatroomService的onMessageStatusChanged事件流。
监听消息附件上传/下载进度事件，请使用ChatroomService的onMessageAttachmentProgressUpdate。

聊天室通知消息

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

NIMChatroomNotificationTypes	说明
chatRoomClose	聊天室被关闭了
chatRoomCommonAdd	成员设定为固定成员
chatRoomCommonRemove	成员取消固定成员
chatRoomInfoUpdated	聊天室信息被更新了
chatRoomManagerAdd	设置为管理员
chatRoomManagerRemove	取消管理员
chatRoomMemberBlackAdd	成员被加黑
chatRoomMemberBlackRemove	成员被取消黑名单
chatRoomMemberExit	成员离开聊天室
chatRoomMemberIn	成员进入聊天室
chatRoomMemberKicked	成员被踢了
chatRoomMemberMuteAdd	成员被设置禁言
chatRoomMemberTempMuteAdd	新增临时禁言
chatRoomMemberTempMuteRemove	主动解除临时禁言
chatRoomMyRoomRoleUpdated	成员主动更新了聊天室内的角色信息(仅指 nick/avator/ext)
chatRoomQueueBatchChange	队列批量变更
chatRoomQueueChange	队列中有变更
chatRoomRoomDeMuted	聊天室解除全体禁言状态
chatRoomRoomMuted	聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态

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

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

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

聊天室通知解析步骤：

通过 NIMChatRoomMessage.messageType 获取消息类型，若为 NIMMessageType.notification ，则为聊天室通知消息。
将 NIMChatRoomMessage.messageAttachment 获取的附件对象强类型转换为 NIMChatroomNotificationAttachment。
通过 NIMChatroomNotificationAttachment.type 获取具体的 NotificationType 。
根据对应的 NotificationType 将 NIMChatRoomMessage.messageAttachment 得到的附件对象强转为对应的 NIMChatroomNotificationAttachment 或其子类）。

NIMChatroomNotificationAttachment 参数说明：

方法	说明
type	通知类型，参考 `NIMChatroomNotificationTypes`
extension	获取聊天室通知扩展字段
operator	获取该操作的发起者的账号
operatorNick	获取该操作的发起者的昵称
targets	获取该操作的承受者的账号列表
targetNicks	获取该操作的承受者的昵称列表

示例：

dart/// 聊天室通知类型
class NIMChatroomNotificationTypes {
    static String typeToString(int type) {
      switch (type) {
        case chatRoomMemberIn:
          return 'chatRoomMemberIn';
        case chatRoomMemberExit:
          return 'chatRoomMemberExit';
        case chatRoomMemberBlackAdd:
          return 'chatRoomMemberBlackAdd';
        case chatRoomMemberBlackRemove:
          return 'chatRoomMemberBlackRemove';
        case chatRoomMemberMuteAdd:
          return 'chatRoomMemberMuteAdd';
        case chatRoomMemberMuteRemove:
          return 'chatRoomMemberMuteRemove';
        case chatRoomManagerAdd:
          return 'chatRoomManagerAdd';
        case chatRoomManagerRemove:
          return 'chatRoomManagerRemove';
        case chatRoomCommonAdd:
          return 'chatRoomCommonAdd';
        case chatRoomCommonRemove:
          return 'chatRoomCommonRemove';
        case chatRoomClose:
          return 'chatRoomClose';
        case chatRoomInfoUpdated:
          return 'chatRoomInfoUpdated';
        case chatRoomMemberKicked:
          return 'chatRoomMemberKicked';
        case chatRoomMemberTempMuteAdd:
          return 'chatRoomMemberTempMuteAdd';
        case chatRoomMemberTempMuteRemove:
          return 'chatRoomMemberTempMuteRemove';
        case chatRoomMyRoomRoleUpdated:
          return 'chatRoomMyRoomRoleUpdated';
        case chatRoomQueueChange:
          return 'chatRoomQueueChange';
        case chatRoomRoomMuted:
          return 'chatRoomRoomMuted';
        case chatRoomRoomDeMuted:
          return 'chatRoomRoomDeMuted';
        case chatRoomQueueBatchChange:
          return 'chatRoomQueueBatchChange';
        default:
          return 'unknown';
      }
    }
}

查询云端历史消息

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

查询云端历史消息

以 startTime（单位毫秒）为查询起点，选择查询方向往前或者往后拉取 limit 条消息。拉取到的消息中也包含聊天室通知消息。同时，可以指定要拉取的消息类型，如果不指定，会包含所有消息类型；

查询结果排序与查询方向有关，若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序。

dartclass ChatroomService {
  /// 获取历史消息,可选择给定时间往前或者往后查询，若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序。
  ///
  /// [roomId]    聊天室id <p>
  /// [startTime] 时间戳，单位毫秒 <p>
  /// [limit]     可拉取的消息数量 <p>
  /// [direction] 查询方向 <p>
  /// [messageTypeList] 查询的消息类型
  Future<NIMResult<List<NIMChatroomMessage>>> fetchMessageHistory({
    required String roomId,
    required int startTime,
    required int limit,
    required QueryDirection direction,
    List<NIMMessageType>? messageTypeList,
  });
}

参数说明

参数	说明
roomId	聊天室 id
startTime	时间戳，单位毫秒
limit	可拉取的消息数量，最多 100 条
direction	查询方向
messageTypeList	查询消息类型

QueryDirection 属性说明

QueryDirection 属性	说明
QUERY_OLD	查询比锚点时间更早的消息
QUERY_NEW	查询比锚点时间更晚的消息

示例

dart        NimCore.instance.chatroomService.fetchMessageHistory(
            roomId: '123456',
            startTime: DateTime.now().millisecondsSinceEpoch,
            limit: 10,
            direction: QueryDirection.QUERY_OLD,
            messageTypeList: [NIMMessageType.text],
        ).then((messages) {
            var index = 0;
            messages.data?.forEach((message) {
              print(
                  'ChatroomService##message history: ${index++} ${message.fromAccount} ${message.fromNickname} '
                  '\'${message.content}\'');
            });
        });

聊天室信息管理

获取聊天室信息

此接口可以向服务器获取聊天室信息。SDK 不提供聊天室信息的缓存，开发者可根据需要自己做缓存。聊天室基本信息的扩展字段需要在服务器端设置，客户端 SDK 只提供查询。

API 原型

dartclass ChatroomService {
    /// 获取当前聊天室信息
    Future<NIMResult<NIMChatroomInfo>> fetchChatroomInfo(String roomId);
}

示例

dartNimCore.instance.chatroomService.fetchChatroomInfo('123456')
    .then(
        (value) {
            print(
                'ChatroomService##fetch updated chatroom info: ${value.data?.name} '
                '${value.data?.announcement}');
        }
    );

修改聊天室信息

支持修改聊天室信息，只有创建者和管理员拥有权限修改聊天室信息。可以设置修改是否通知，若设置通知，聊天室内会收到类型为NIMChatroomNotificationTypes#chatRoomInfoUpdated的消息。

API 原型

dartclass ChatroomService {
  /// 更新聊天室信息
  Future<NIMResult<void>> updateChatroomInfo({
    required String roomId,
    required NIMChatroomUpdateRequest request,
    bool needNotify = true,
    Map<String, dynamic>? notifyExtension,
  });
}

参数说明

参数	说明
roomId	聊天室 id
request	可更新的聊天室信息
needNotify	是否通知
notifyExtension	更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
NIMChatroomUpdateRequest	说明
:-----------------------	:--------------------------------------------------------------------------------------------------
name	聊天室名称
announcement	聊天室公告
broadcastUrl	视频直播拉流地址
extension	第三方扩展字段
queueLevel	队列管理权限，如是否有权限提交他人 key 和信息到队列; 0 表示所有人有权限，1 表示只有主播管理员有权限

示例

dart        NimCore.instance.chatroomService
              .updateChatroomInfo(
            roomId: '123456',
            request: NIMChatroomUpdateRequest(
              announcement: '修改群公告',
            ),
            needNotify: true,
        ).then((value) {
            print(
                'ChatroomService##set chatroom announcement:  ${value.code} ${value.errorDetails}');
        });

聊天室成员管理

聊天室成员概述

关于聊天室成员：

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

聊天室成员原型：

类型	NIMChatroomMember 属性	说明
String	roomId	获取聊天室 id
String	account	获取成员帐号
String?	avatar	获取头像。可从 NimUserInfo 中取 avatar，可以由用户进聊天室时提交
int?	enterTime	获取进入聊天室时间。对于离线成员该字段为空
Map<String, dynamic>?	extension	获取扩展字段。长度限制 4k，可以由用户进聊天室时提交
NIMChatroomMemberType	memberType	获取成员类型。成员类型：主要分为游客和非游客
String?	nickname	获取昵称。可从 NimUserInfo 中取，也可以由用户进聊天室时提交
int?	tempMuteDuration	获取临时禁言解除时长，单位秒
bool	isInBlackList	判断用户是否在黑名单中
bool	isMuted	判断用户是否被禁言
bool	isOnline	判断用户是否处于在线状态仅特殊成员才可能离线，对游客/匿名用户而言只能是在线
bool	isTempMuted	判断用户是否被临时禁言
bool	isValid	判断是否有效

关于 NIMChatroomMemberType 成员类型说明：

NIMChatroomMemberType 属性	说明
unknown	未知
guest	游客
restricted	受限用户（非游客）= 被禁言 + 被拉黑的用户
normal	普通成员（非游客）
creator	创建者（非游客）
manager	管理员（非游客）
anonymous	匿名游客

获取聊天室成员

分页获取聊天室成员

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

API 原型

dartclass ChatroomService {
  /// 获取当前聊天室成员
  ///
  /// [roomId]    聊天室id <p>
  /// [queryType] 查询的类型, [NIMChatroomMemberQueryType]
  /// [limit]     可拉取的消息数量 <p>
  /// [lastMemberAccount] 最后一位锚点的成员账号，不包括此成员。如果为空会使用当前服务器最新时间开始查询，即第一页。 <p>
  Future<NIMResult<List<NIMChatroomMember>>> fetchChatroomMembers({
    required String roomId,
    required NIMChatroomMemberQueryType queryType,
    required int limit,
    String? lastMemberAccount,
  });
}

参数说明

参数	说明
roomId	聊天室 id
queryType	成员查询类型。见 NIMChatroomMemberQueryType
lastMemberAccount	最后一位锚点的成员账号，不包括此成员。如果为空会使用当前服务器最新时间开始查询，即第一页。
limit	人数限制
NIMChatroomMemberQueryType	说明
:-------------------------------	:--------------------------------------------------------------------------------------------------------------------
allNormalMember	固定成员（包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单), 即使非在线也可以在列表中看到,有数量限制）
onlineNormalMember	仅在线的固定成员
onlineGuestMemberByEnterTimeDesc	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间倒序排序，进入时间越晚的越靠前
onlineGuestMemberByEnterTimeAsc	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间顺序排序，进入时间越早的越靠前

示例

dart
    NimCore.instance.chatroomService.fetchChatroomMembers(
      roomId: chatroomId,
      queryType: NIMChatroomMemberQueryType.allNormalMember,
      limit: 10,
    ).then((result) {
      var index = 0;
      result.data?.forEach((member) {
        print(
            'ChatroomService fetchChatroomMembers ##member_${index++}: ${member.account} ${member.nickname} ${member.memberType}');
      });
    });

获取指定聊天室成员

dartclass ChatroomService {
  /// 获取当前聊天室成员
  ///
  /// [roomId]      聊天室id <p>
  /// [accountList] 成员账号列表 <p>
  Future<NIMResult<List<NIMChatroomMember>>> fetchChatroomMembersByAccount({
    required String roomId,
    required List<String> accountList,
  });
}

示例

dart    NimCore.instance.chatroomService.fetchChatroomMembersByAccount(
      roomId: chatroomId,
      accountList: ['account1', 'account2'],
    ).then((result) {
      var index = 0;
      result.data?.forEach((member) {
        print(
            'ChatroomService fetchChatroomMembers ##member_${index++}: ${member.account} ${member.nickname} ${member.memberType}');
      });
    });

修改自身信息

支持更新本人聊天室成员信息。目前只支持昵称，头像和扩展字段的更新。可以设置更新是否通知，若设置通知，聊天室内会收到类型为NIMChatroomNotificationTypes#chatroomMyRoomRoleUpdated的消息。

dartclass ChatroomService {
  /// 更新聊天室内的自身信息
  /// [roomId]               聊天室id
  /// [request]              可更新的本人角色信息
  /// [needNotify]           是否通知
  /// [notifyExtension]      更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
  Future<NIMResult<void>> updateChatroomMyMemberInfo({
    required String roomId,
    required NIMChatroomUpdateMyMemberInfoRequest request,
    bool needNotify = true,
    Map<String, dynamic>? notifyExtension,
  });
}

参数说明

参数	说明
roomId	聊天室 id
request	可更新的本人角色信息
needNotify	是否通知
notifyExtension	更新操作扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中

NIMChatroomUpdateMyMemberInfoRequest 接口说明

类型	NIMChatroomUpdateMyMemberInfoRequest 接口	说明
String?	avatar	获取聊天室内的头像
Map<String, dynamic>?	extension	获取扩展字段
String?	nickname	获取聊天室内的昵称
bool	needSave	更新的信息是否需要做持久化，只对固定成员生效，默认 false

示例

dart    /// 以更新自己的昵称为例
    NimCore.instance.chatroomService
        .updateChatroomMyMemberInfo(
      roomId: chatroomId,
      request: NIMChatroomUpdateMyMemberInfoRequest(
        nickname: '新昵称',
        needSave: true,
      ),
    ).then((value) {
      print(
          'ChatroomService##update chatroom my info:  ${value.code} ${value.errorDetails}');
    });

添加/移除管理员

dartclass ChatroomService {
  ///
  /// 设置/取消设置聊天室管理员
  ///
  /// [isAdd]        true:设置, false:取消设置
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  Future<NIMResult<NIMChatroomMember>> markChatroomMemberBeManager({
    required bool isAdd,
    required NIMChatroomMemberOptions options,
  });
}

参数说明

返回值	NIMChatroomMemberOptions 接口	说明
String	roomId	获取聊天室 id
String	account	获取成员帐号
Map<String, dynamic>?	getNotifyExtension()	获取通知事件中开发者定义的扩展字段

示例

dart    /// 以设置为管理员为例
    NimCore.instance.chatroomService
        .markChatroomMemberBeManager(
      isAdd: true,
      options: NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
    ).then((value) {
      print(
          'ChatroomService##markChatroomMemberBeManager:  ${value.code} ${value.errorDetails}');
    });

添加/移除普通成员

dartclass ChatroomService {
  ///
  /// 设置/取消设置聊天室普通成员
  ///
  /// [isAdd]        true:设置, false:取消设置
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  Future<NIMResult<NIMChatroomMember>> markChatroomMemberBeNormal({
    required bool isAdd,
    required NIMChatroomMemberOptions options,
  });
}

示例

java/// 以设为普通成员为例
    NimCore.instance.chatroomService
        .markChatroomMemberBeNormal(
      isAdd: true,
      options: NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
    ).then((value) {
      print(
          'ChatroomService##markChatroomMemberBeNormal:  ${value.code} ${value.errorDetails}');
    });

添加/移除黑名单用户

dartclass ChatroomService {
  ///
  /// 添加/移出聊天室黑名单
  ///
  /// [isAdd]        true:设置, false:取消设置
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  Future<NIMResult<NIMChatroomMember>> markChatroomMemberInBlackList({
    required bool isAdd,
    required NIMChatroomMemberOptions options,
  });
}

示例

dart    /// 以添加到黑名单为例
    NimCore.instance.chatroomService
        .markChatroomMemberInBlackList(
      isAdd: true,
      options: NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
    ).then((value) {
      print(
          'ChatroomService##markChatroomMemberInBlackList:  ${value.code} ${value.errorDetails}');
    });

添加/移除禁言用户

添加到禁言名单时, 会收到类型为 chatRoomMemberMuteAdd 的聊天室通知消息。

取消禁言时, 会收到类型为 chatRoomMemberMuteRemove 的聊天室通知消息。

dartclass ChatroomService {
  ///
  /// 添加/解除禁言聊天室成员
  ///
  /// [isAdd]        true:设置, false:取消设置
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  Future<NIMResult<NIMChatroomMember>> markChatroomMemberMuted({
    required bool isAdd,
    required NIMChatroomMemberOptions options,
  });
}

示例

dart/// 以添加到禁言名单为例
    NimCore.instance.chatroomService
        .markChatroomMemberMuted(
      isAdd: true,
      options: NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
    ).then((value) {
      print(
          'ChatroomService##markChatroomMemberMuted:  ${value.code} ${value.errorDetails}');
    });

踢出成员

踢出成员。仅管理员可以踢；如目标是管理员，仅创建者可以踢。

当有人被踢出聊天室时，会收到类型为 chatRoomMemberKicked 的聊天室通知消息。

可以添加被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中。通知扩展字段最长 1K；扩展字段类型为 Map<String, dynamic>。

dartclass ChatroomService {
  ///
  /// 踢掉聊天室特定成员
  ///
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  Future<NIMResult<void>> kickChatroomMember(NIMChatroomMemberOptions options);
}

示例

dart    NimCore.instance.chatroomService
        .kickChatroomMember(
      NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
    ).then((value) {
      print(
          'ChatroomService##kickChatroomMember:  ${value.code} ${value.errorDetails}');
    });

临时禁言成员

设置临时禁言时, 会收到类型为 chatRoomMemberTempMuteAdd 的聊天室通知消息。

取消临时禁言时, 会收到类型为 chatRoomMemberTempMuteRemove 的聊天室通知消息。

聊天室支持设置临时禁言，禁言时长时间到了，自动取消禁言。设置临时禁言成功后的通知消息中，包含的时长是禁言剩余时长。若设置禁言时长为 0，表示取消临时禁言。若第一次设置的禁言时长还没结束，又设置第二次临时禁言，以第二次设置的时间开始计时。

dartclass ChatroomService {
  ///
  /// 添加/解除临时禁言聊天室成员
  ///
  /// [duration]     禁言时长，单位ms。设置为 0 会取消禁言
  /// [memberOption] 请求参数，包含聊天室id，帐号id以及可选的扩展字段
  /// [needNotify]   是否需要发送广播通知，true：通知，false：不通知
  Future<NIMResult<void>> markChatroomMemberTempMuted({
    required int duration,
    required NIMChatroomMemberOptions options,
    bool needNotify = false,
  });
}

参数说明

参数	说明
duration	禁言时长,单位秒
memberOption	请求参数，包含聊天室 id，帐号 id 以及可选的扩展字段
needNotify	是否需要发送广播通知，true：通知，false：不通知

示例

dart/// 以发送广播通知，并且临时禁言10秒为例
    NimCore.instance.chatroomService
        .markChatroomMemberTempMuted(
      duration: 10 * 1000,
      options: NIMChatroomMemberOptions(
        roomId: '123456',
        account: 'account',
      ),
      needNotify: true,
    ).then((value) {
      print(
          'ChatroomService##markChatroomMemberTempMuted:  ${value.code} ${value.errorDetails}');
    });

聊天室队列

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

获取聊天室队列

dartclass ChatroomService {
  /// 获取聊天室队列
  ///
  /// [roomId] 聊天室ID <p>
  Future<NIMResult<List<NIMChatroomQueueEntry>>> fetchChatroomQueue(
      String roomId);
}

示例

dart    NimCore.instance.chatroomService
        .fetchChatroomQueue('123456')
        .then((value) {
      print('ChatroomService##poll queue: ${value.code} ${value.errorDetails} '
          '${value.data?.map((e) => '${e.key}:${e.value}').toList()}');
    });

加入或者更新队列元素

用户使用该接口加入或更新的元素，当 isTransient 参数为 true 时，表示当该用户掉线或退出聊天室时，服务器会自动删除该用户加入或更新的元素。

同时，服务器将发出聊天室通知消息，通知消息的类型为 NIMChatroomNotificationTypes#chatRoomQueueBatchChange，通知消息的附件类型为 NIMChatroomQueueChangeAttachment，该通知消息属于队列变更通知，所以附件类型中包含了队列变更类型 NIMChatroomQueueChangeType#partialClear。

dartclass ChatroomService {
  /// 更新聊天室队列
  ///
  /// [roomId] 聊天室ID <p>
  /// [entry] 要更新的队列项 <p>
  /// [isTransient] (可选参数，不传默认false)。true表示当提交这个新元素的用户从聊天室掉线或退出的时候，需要删除这个元素；默认false表示不删除
  Future<NIMResult<void>> updateChatroomQueueEntry({
    required String roomId,
    required NIMChatroomQueueEntry entry,
    bool isTransient = false,
  });
}

参数说明

参数	说明
roomId	聊天室 id
entry	新元素
isTransient	(可选参数) true 表示当提交这个新元素的用户从聊天室掉线或退出的时候，需要删除这个元素；默认 false 表示不删除

NIMChatroomQueueEntry 说明：

参数	说明
key	新元素（或待更新元素）的唯一键
value	新元素（待待更新元素）的内容

NIMChatroomQueueChangeAttachment 说明

类型	NIMChatroomQueueChangeAttachment 接口	说明
NIMChatroomQueueChangeType	queueChangeType	返回队列变更类型，值为 NIMChatroomQueueChangeType
Map<String, String>?	contentMap	当用户掉线或退出聊天室时，返回用户使用 updateQueueEx 接口，并设置 isTransient 参数为 true 时，加入或更新的元素

示例

dartNimCore.instance.chatroomService
        .updateChatroomQueueEntry(
      roomId: chatroomId,
      entry: NIMChatroomQueueEntry(
        key: 'key',
        value: 'value',
      ),
    ).then((value) {
      print(
          'ChatroomService##updateChatroomQueueEntry: ${value.code} ${value.errorDetails}');
    });

批量更新队列元素

只会更新已经存在的 key，不会加入新元素。

dartclass ChatroomService {
  /// 批量更新聊天室队列
  ///
  /// [roomId]          聊天室ID <p>
  /// [entry]           要更新的队列项列表 <p>
  /// [needNotify]      是否需要发送广播通知 <p>
  /// [notifyExtension] 通知中的自定义字段 <p>
  /// 返回不在队列中的元素列表
  Future<NIMResult<List<String>>> batchUpdateChatroomQueue({
    required String roomId,
    required List<NIMChatroomQueueEntry> entryList,
    bool needNotify = true,
    Map<String, Object>? notifyExtension,
  });
}

示例

dartNimCore.instance.chatroomService
        .batchUpdateChatroomQueue(
      roomId: chatroomId,
      entryList: [
        NIMChatroomQueueEntry(
          key: 'key',
          value: 'value',
      )],
    ).then((value) {
      print(
          'ChatroomService##batchUpdateChatroomQueue: ${value.code} ${value.errorDetails}');
    });

移除指定队列元素

key 是唯一键。key 若为 null，则表示取出头元素。若不为 null，则表示取出指定元素。

dartclass ChatroomService {
  /// 从列表中删除某个元素
  ///
  /// [roomId] 聊天室ID <p>
  /// [key] 要删除的key，null表示移除队头元素 <p>
  Future<NIMResult<NIMChatroomQueueEntry>> pollChatroomQueueEntry(
      String roomId, String? key);
}

参数说明

参数	说明
roomId	聊天室 id
key	需要取出的元素的唯一键。若为 null，则表示取出队头元素

示例

dart    NimCore.instance.chatroomService
        .pollChatroomQueueEntry(
      chatroomId,
      'key',
    ).then((value) {
      print(
          'ChatroomService##batchUpdateChatroomQueue: ${value.code} ${value.errorDetails}');
    });

清空队列

dartclass ChatroomService {
  /// 清空聊天室队列
  Future<NIMResult<void>> clearChatroomQueue(String roomId);
}

示例

java    NimCore.instance.chatroomService
        .clearChatroomQueue(
      '123456',
    ).then((value) {
      print(
          'ChatroomService##clearChatroomQueue: ${value.code} ${value.errorDetails}');
    });

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

功能概述
进入聊天室
非独立模式
独立模式
聊天室多端登录
监听聊天室连接变化
监听被踢出
离开聊天室
聊天室消息收发
发送聊天室消息
发送消息配置选项
接收聊天室消息
聊天室通知消息
查询云端历史消息
查询云端历史消息
聊天室信息管理
获取聊天室信息
修改聊天室信息
聊天室成员管理
聊天室成员概述
获取聊天室成员
分页获取聊天室成员
获取指定聊天室成员
修改自身信息
添加/移除管理员
添加/移除普通成员
添加/移除黑名单用户
添加/移除禁言用户
踢出成员
临时禁言成员
聊天室队列
获取聊天室队列
加入或者更新队列元素
批量更新队列元素
移除指定队列元素
清空队列