聊天室成员管理

聊天室成员概述

关于聊天室成员：

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

聊天室成员原型：

返回值	ChatRoomMember 接口	说明
String	getAccount()	获取成员帐号
String	getAvatar()	获取头像。可从 NimUserInfo 中取 avatar，可以由用户进聊天室时提交
long	getEnterTime()	获取进入聊天室时间。对于离线成员该字段为空
Map	getExtension()	获取扩展字段。长度限制 4k，可以由用户进聊天室时提交
int	getMemberLevel()	获取成员级别。大于等于 0 表示用户开发者可以自定义的级别
MemberType	getMemberType()	获取成员类型。成员类型：主要分为游客和非游客
String	getNick()	获取昵称。可从 NimUserInfo 中取，也可以由用户进聊天室时提交
String	getRoomId()	获取聊天室 id
long	getTempMuteDuration()	获取临时禁言解除时长，单位秒
long	getUpdateTime()	获取固定成员的记录更新时间，用于固定成员列表的排列查询
boolean	isInBlackList()	判断用户是否在黑名单中
boolean	isMuted()	判断用户是否被禁言
boolean	isOnline()	判断用户是否处于在线状态 仅特殊成员才可能离线，对游客/匿名用户而言只能是在线
boolean	isTempMuted()	判断用户是否被临时禁言
boolean	isValid()	判断是否有效
void	setAccount(String account)	设置用户帐号
void	setAvatar(String avatar)	设置成员头像
void	setEnterTime(long enterTime)	设置进入聊天室时间
void	setExtension(Map extension)	设置扩展字段
void	setInBlackList(boolean inBlackList)	设置是否在黑名单中
void	setMemberLevel(int memberLevel)	设置成员等级
void	setMemberType(MemberType type)	设置成员类型
void	setMuted(boolean muted)	设置是否禁言
void	setNick(String nick)	设置成员昵称
void	setOnline(boolean online)	设置在线状态
void	setRoomId(String roomId)	设置聊天室id
void	setTempMuted(boolean tempMuted)	设置是否临时禁言
void	setTempMuteDuration(long tempMuteDuration)	设置临时禁言解除时长
void	setUpdateTime(long updateTime)	设置固定成员的更新时间
void	setValid(boolean valid)	设置是否有效

关于MemberQueryType 属性说明：

MemberQueryType 属性	说明
GUEST	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限)
NORMAL	固定成员 （包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单), 即使非在线也可以在列表中看到,有数量限制 ）
ONLINE_NORMAL	仅在线的固定成员
GUEST_DESC	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间倒序排序，进入时间越晚的越靠前
GUEST_ASC	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间顺序排序，进入时间越早的越靠前
UNKNOWN	未知

获取聊天室成员

分页获取聊天室成员

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

• API 原型

java/**
 * 获取聊天室成员信息
 *
 * @param roomId          聊天室id
 * @param memberQueryType 成员查询类型。
 * @param time            固定成员列表用updateTime,
 *                        游客列表用进入enterTime，
 *                        填0会使用当前服务器最新时间开始查询，即第一页，单位毫秒
 * @param limit           人数限制
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
 */
InvocationFuture<List<ChatRoomMember>> fetchRoomMembers(String roomId, MemberQueryType memberQueryType, long time, int limit);

• 参数说明

参数	说明
roomId	聊天室id
memberQueryType	成员查询类型。见 MemberQueryType
time	固定成员列表用 updateTime, 游客列表用进入 enterTime， 填 0 会使用当前服务器最新时间开始查询，即第一页，单位毫秒
limit	人数限制

• 示例

java// 以游客为例，从最新时间开始，查询10条
NIMClient.getService(ChatRoomService.class).fetchRoomMembers(roomId, MemberQueryType.GUEST, 0, 10).setCallback(new RequestCallbackWrapper<List<ChatRoomMember>>() {
    @Override
    public void onResult(int code, List<ChatRoomMember> result, Throwable exception) {
       ...
    }
});

获取指定聊天室成员

java/**
 * 根据用户id获取聊天室成员信息
 *
 * @param roomId   聊天室id
 * @param accounts 成员帐号列表
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
 */
InvocationFuture<List<ChatRoomMember>> fetchRoomMembersByIds(String roomId, List<String> accounts)

• 示例

javaList<String> accounts = new ArrayList<>();
accounts.add(account);

NIMClient.getService(ChatRoomService.class).fetchRoomMembersByIds(roomId, accounts)
	     .setCallback(new RequestCallbackWrapper<List<ChatRoomMember>>() { ... });

获取聊天室机器人列表

聊天室独立模式下，由于不存在 IM 连接，无法同步机器人列表，因此需要调用此接口拉取机器人列表。建议在进入聊天室之后调用此接口，并且做好频控措施，以防用户频繁切换聊天室时该接口频率过高。

• API 原型

java/**
 * 独立聊天室场景下，获取当前全部聊天室机器人
 *
 * @param roomId 当前聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<List<NimRobotInfo>> pullAllRobots(String roomId);

• 示例

java
/**
 * 拉取机器人信息最短间隔 5min
 */
private static final long MIN_PULL_ROBOT_INTERNAL = 5 * 60 * 1000;

private long lastTime = 0L;

/**
 *  独立模式进入聊天室之后调用
 *
 *  最短时间间隔 MIN_PULL_ROBOT_INTERNAL
 * @param roomId
 */
public void pullRobotListIndependent(String roomId) {
    if (System.currentTimeMillis() - lastTime < MIN_PULL_ROBOT_INTERNAL) {
        return;
    }

    NIMClient.getService(ChatRoomService.class).pullAllRobots(roomId).setCallback(new RequestCallbackWrapper<List<NimRobotInfo>>() {
        @Override
        public void onResult(int code, List<NimRobotInfo> result, Throwable exception) {
            if (code == 200 && result != null) {
                lastTime = System.currentTimeMillis();
                // 更新缓存
            }
        }
    });
}

修改自身信息

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

java/**
 * 更新本人在聊天室内的信息
 *
 * @param roomId               聊天室id
 * @param chatRoomMemberUpdate 可更新的本人角色信息
 * @param needNotify           是否通知
 * @param notifyExtension      更新操作扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
 * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension);

java/**
 * 更新本人在聊天室内的信息
 *
 * @param roomId               聊天室id
 * @param chatRoomMemberUpdate 可更新的本人角色信息
 * @param needNotify           是否通知
 * @param notifyExtension      更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中,最大长度2k
 * @param antiSpamConfig       反垃圾配置参数
 * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension,AntiSpamConfig antiSpamConfig);

• 参数说明

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

ChatRoomMemberUpdate 接口说明

返回值	ChatRoomMemberUpdate 接口	说明
String	getAvatar()	获取聊天室内的头像
Map	getExtension()	获取扩展字段
String	getNick()	获取聊天室内的昵称
boolean	isNeedSave()	更新的信息是否需要做持久化，只对固定成员生效，默认 false，v3.8.0增加
void	setAvatar(String avatar)	设置聊天室内的头像
void	setExtension(Map extension)	设置扩展字段，长度限制为 4k
void	setNeedSave(boolean needSave)	设置是否需要持久化，只对固定成员生效，v3.8.0增加
void	setNick(String nick)	设置聊天室内的昵称

• 示例

java// 以更新自己的昵称为例
ChatRoomMemberUpdate update = new ChatRoomMemberUpdate();
update.setNick("我的新昵称");

NIMClient.getService(ChatRoomService.class).updateMyRoomRole(roomId, update, false, "").setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});

添加/移除管理员

java/**
 * 设为/取消聊天室管理员
 *
 * @param isAdd        true:设为, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomManager(boolean isAdd, MemberOption memberOption);

• 参数说明

返回值	MemberOption 接口	说明
String	getAccount()	获取成员帐号
Map	getNotifyExtension()	获取通知事件中开发者定义的扩展字段
String	getRoomId()	获取聊天室id
void	setAccount(String account)	设置成员帐号
void	setNotifyExtension(Map notifyExtension)	设置通知事件中的扩展字段
void	setRoomId(String roomId)	设置聊天室 id

• 示例

java// 以设置为管理员为例
NIMClient.getService(ChatRoomService.class)
        .markChatRoomManager(true, new MemberOption(roomId, account))
        .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

添加/移除普通成员

java/**
 * 设为/取消聊天室普通成员
 *
 * @param isAdd        true:设为, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markNormalMember(boolean isAdd, MemberOption memberOption);

• 示例

java// 以设为普通成员为例
NIMClient.getService(ChatRoomService.class).markNormalMember(true, new MemberOption(roomId, account)))
        .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
               // 成功
            }

            @Override
            public void onFailed(int code) {
				// 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

添加/移除黑名单用户

java/**
 * 添加/移出聊天室黑名单
 *
 * @param isAdd        true:添加, false:移出
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomBlackList(boolean isAdd, MemberOption memberOption);

• 示例

java// 以添加到黑名单为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomBlackList(true, option).setCallback(new RequestCallback<ChatRoomMember>() {
        @Override
        public void onSuccess(ChatRoomMember param) {
        // 成功
        }

        @Override
        public void onFailed(int code) {
        // 失败
        }

        @Override
        public void onException(Throwable exception) {
		// 错误
        }
});

添加/移除禁言用户

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

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

java/**
 * 添加到禁言名单/取消禁言
 *
 * @param isAdd        true:添加, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomMutedList(boolean isAdd, MemberOption memberOption);

• 示例

java// 以添加到禁言名单为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomMutedList(true, option)
         .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

踢出成员

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

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

可以添加被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中。通知扩展字段最长 1K；扩展字段需要传入 Map<String,Object>， SDK 会负责转成 Json String。

java/**
 * 踢掉特定成员
 *
 * @return InvocationFuture 可以设置回调函数。踢掉成员完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> kickMember(String roomId, String account, Map<String, Object> notifyExtension);

• 参数说明

参数	说明
roomId	聊天室 id
account	踢出成员帐号。仅管理员可以踢；如目标是管理员仅创建者可以踢
notifyExtension	被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中

• 示例

javaMap<String, Object> reason = new HashMap<>();
reason.put("reason", "kick");
NIMClient.getService(ChatRoomService.class).kickMember(roomId, account, reason).setCallback(new RequestCallback<Void>() { ... });

临时禁言成员

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

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

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

java/**
 * 设置聊天室成员临时禁言
 *
 * @return InvocationFuture 可以设置回调函数。如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> markChatRoomTempMute(boolean needNotify, long duration, MemberOption memberOption);

• 参数说明

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

• 示例

java// 以发送广播通知，并且临时禁言10秒为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomTempMute(true, 10, option)
        .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });