聊天室成员管理
更新时间: 2024/03/14 16:33:01
聊天室成员管理
聊天室成员概述
关于聊天室成员:
- 聊天室成员包括固定成员和非固定成员(临时成员/游客)。固定成员上限是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) {
// 错误
}
});