群组功能
群组功能概述
网易云通信 SDK 提供了普通群 (TeamTypeEnum#Normal)，以及高级群 (TeamTypeEnum#Advanced)两种形式的群聊功能。高级群拥有更多的权限操作，两种群聊形式在共有操作上保持了接口一致。在群组中，当前会话的 ID 就是群组的 ID。
- 普通群
开发手册中所提及的普通群都等同于 Demo 中的讨论组。普通群没有权限操作，适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对普通群进行增减员操作，普通成员只能对普通群进行增员操作。在添加新成员的时候，并不需要经过对方同意。
- 高级群
高级群在权限上有更多的限制，权限分为群主、管理员、以及群成员。2.4.0之前版本在添加成员的时候需要对方接受邀请；2.4.0版本之后，可以设定被邀请模式（是否需要对方同意）。高级群可以覆盖所有普通群的能力，建议开发者创建时选用高级群。
群组消息
群聊消息
群聊消息收发和管理和单人聊天完全相同，仅在 SessionTypeEnum 上做了区分，详见消息收发节。
设置群聊消息提醒类型
可以对某个群设置消息提醒类型，群消息提醒分为全部提醒、仅管理员消息提醒、全部不提醒等三种，默认为全部提醒，普通群不支持设置仅管理员消息提醒。设置之后如果新消息不满足消息提醒的条件，用户仍然会收到这个消息，如果开发者使用的是网易云通信内建的消息提醒，用户收到新消息后不会再用通知栏提醒，如果用户使用的 iOS 客户端，则他将收不到该群聊消息的 APNS 推送。如果开发者自行实现状态栏提醒，可通过 Team 的 getMessageNotifyType 接口获取提醒配置，并决定是不是要显示通知。群聊消息提醒设置可以漫游。
- API 原型
/**
* 设置指定群消息通知类型
*
* @param teamId 群组ID
* @param notifyType 通知类型枚举
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> muteTeam(String teamId, TeamMessageNotifyTypeEnum notifyType);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群组ID |
| TeamMessageNotifyTypeEnum | 消息提醒类型枚举，分别为全部提醒、仅管理员消息提醒、全部不提醒 |
- 示例
// 以设置 “仅管理员消息提醒” 为例
TeamMessageNotifyTypeEnum type = TeamMessageNotifyTypeEnum.Manager;
NIMClient.getService(TeamService.class).muteTeam(teamId, type).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 设置成功
}
@Override
public void onFailed(int code) {
// 设置失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});指定群成员强制推送
群消息支持设置强制推送。强制推送优先级最高，
1、打开强推开关，即使关闭消息提醒，依然能收到通知栏提醒，但是声音和震动跟随本机设置。
2、打开强推开关，即使设置了 桌面端在线时不推送，依然能收到通知栏提醒。
3、无论是否打开强推开关，设置了强推通知文本内容并且位于强推列表中的成员（若强推列表为 null，则表示本群所有成员），收到的消息提醒均显示强推通知文本。
4、强推列表可以配置需要强制推送的群成员，若为 null ，则表示该群所有群成员均收到强制推送消息。
5、打开强推开关，也打开免打扰设置。有通知栏提醒，但是没有声音和震动。
- 参数说明
MemberPushOption 接口说明
| 返回值 | MemberPushOption接口 | 说明 |
|---|---|---|
| List |
getForcePushList() | 返回强制推送的账号列表 |
| String | getForcePushContent() | 返回强制推送的文案 |
| boolean | isForcePush() | 返回是否强制推送 |
| void | setForcePush(boolean forcePush) | 设置是否强推。 针对 forcePushList 里的帐号， false 为不强推，true 为强推，默认为 true。 对于 forcePushList 中的用户，推送文案为 forcePushContent； 对于不在 forcePushList 中的用户，推送文案为 pushContent； 针对在 forcePushList 中的账号： isForcePush 为true 时，推送文案中不会包含发送者 nick，直接为 forcePushContent； isForcePush 为 false 时，推送文案中目前包含了发送者 nick（暂定），即为 fromNick：forcePushContent |
| void | setForcePushList(List |
设置强推列表， 填 null 表示强推给该会话所有成员， 不为 null 时最大上限账号为100个 |
| void | setForcePushContent(String forcePushContent) | 强推文案（可扩展为区别与普通推送的推送文案），目前限制为500字以内 |
- 示例
// 该帐号为示例，请先注册
String account = "testAccount";
// 群聊才有强推消息
SessionTypeEnum sessionType = SessionTypeEnum.Team;
String text = "指定推送消息";
// 创建一个文本消息
IMMessage textMessage = MessageBuilder.createTextMessage(account, sessionType, text);
// 配置指定成员推送
MemberPushOption memberPushOption = new MemberPushOption();
// 开启强制推送
memberPushOption.setForcePush(true);
// 设置强推文案
memberPushOption.setForcePushContent(textMessage.getContent());
List<String> pushList = new ArrayList<>();
pushList.add("account1");
pushList.add("account2");
// 设置指定推送列表
memberPushOption.setForcePushList(pushList);
textMessage.setMemberPushOption(memberPushOption);
// 发送给对方
NIMClient.getService(MsgService.class).sendMessage(textMessage, false);群已读回执
发送群已读回执消息
IMMessage 新增接口
| 返回值 | IMMessage部分接口 | 说明 |
|---|---|---|
| boolean | needMsgAck() | 是否需要消息已读（主要针对群消息） |
| void | setMsgAck() | 设置该消息为需要消息已读的 |
| boolean | hasSendAck() | 是否已经发送过群消息已读回执 |
- 示例
// 创建待发送消息
IMMessage message = MessageBuilder.createTextMessage(sessionId, SessionTypeEnum.Team, "content");
// 标记该消息需要已读回执反馈
message.setMsgAck();
// 发送消息
NIMClient.getService(MsgService.class).sendMessage(message, false);标记群组消息已读
- 原型
/**
* (群消息接收方)标记群组消息已读
*
* @param message 群组消息
* @return InvocationFuture 可设置回调函数，监听发送结果。
*/
InvocationFuture<Void> sendTeamMessageReceipt(IMMessage message);一般在消息可见时发出已读回执。
- 示例
NIMSDK.getTeamService().sendTeamMessageReceipt(message)批量刷新群组消息已读、未读的数量
- 原型
/**
* (群消息发送方)批量刷新群组消息已读、未读的数量信息，没有异步回调
* 如果已读、未读数有变更，会通过 {@link com.netease.nimlib.sdk.msg.MsgServiceObserve#observeTeamMessageReceipt(Observer, boolean)}来批量通知，没有变更则不会通知
*
* @param messages 请求刷新的群组消息集合
*/
void refreshTeamMessageReceipt(List<IMMessage> messages);一般在加载消息进行批量刷新。反复刷新，SDK实际上不会发出网络请求。只有已读、未读数量有变更，才会通过观察者接口进行通知。该API为异步无回调接口。
- 示例
// messages为接收到的批量消息
NIMSDK.getTeamService().refreshTeamMessageReceipt(messages);查询单条群组消息已读、未读账号列表
- 原型
/**
* (群消息发送方)查询单条群组消息已读、未读账号列表
*
* @param message 待查询的消息
* @return 该消息的已读、未读账号列表
*/
InvocationFuture<TeamMsgAckInfo> fetchTeamMessageReceiptDetail(IMMessage message);- 示例
// message为待查询的消息
NIMSDK.getTeamService().fetchTeamMessageReceiptDetail(message).setCallback(new RequestCallback<TeamMsgAckInfo>() {
@Override
public void onSuccess(TeamMsgAckInfo param) {
// 获取成功
}
@Override
public void onFailed(int code) {
// 获取失败
}
@Override
public void onException(Throwable exception) {
// 异常
}
});群消息已读未读数变更监听
- 原型
/**
* 注册/注销群消息已读回执观察者（群成员发出需要已读回执的消息时，当有群成员已读后，该观察者会回调）
*
* @param observer 观察者，参数为已读回执信息集合
* @param register true为注册，false为注销
*/
public void observeTeamMessageReceipt(Observer<List<TeamMessageReceipt>> observer, boolean register);- 参数说明
TeamMessageReceipt 接口说明
| 返回值 | TeamMessageReceipt 接口 | 说明 |
|---|---|---|
| String | getMsgId() | 获取消息 id |
| int | getAckCount() | 获取已读人数 |
| int | getUnAckCount() | 获取未读人数 |
- 示例
// 注册监听器
NIMClient.getService(MsgServiceObserve.class).observeTeamMessageReceipt(teamMessageReceiptObserver, register);
// 监听器的实现
private Observer<List<TeamMessageReceipt>> teamMessageReceiptObserver = new Observer<List<TeamMessageReceipt>>() {
@Override
public void onEvent(List<TeamMessageReceipt> teamMessageReceipts) {
...
}
};群组管理
获取群组
SDK 提供了两个获取自己加入的所有群的列表的接口，一个是获取所有群（包括高级群和普通群）的接口，另一个是根据类型获取列表的接口。开发者可根据实际产品需求选择使用。
1. 获取我加入的所有群组
- API 原型
异步版本:
/**
* 获取自己加入的群的列表
*
* @return InvocationFuture 可以设置回调函数，如果成功，参数为自己加入的群的列表
*/
InvocationFuture<List<Team>> queryTeamList();同步版本
/**
* 获取自己加入的群的列表(同步版本)
*
* @return 自己加入的群的列表
*/
public List<Team> queryTeamListBlock();- 参数说明
Team函数说明：
| 返回值 | Team函数 | 说明 |
|---|---|---|
| String | getAnnouncement() | 获取群组公告 |
| long | getCreateTime() | 获取群组的创建时间 |
| String | getCreator() | 获取创建群组的用户帐号 |
| String | getExtension() | 获取群组扩展配置。 |
| String | getExtServer() | 获取服务器设置的扩展配置。 |
| String | getIcon() | 获取群头像 |
| String | getId() | 获取群组ID |
| String | getIntroduce() | 获取群组简介 |
| int | getMemberCount() | 获取群组的总成员数 |
| int | getMemberLimit() | 获取群组的成员人数上限 |
| String | getName() | 获取群组名称 |
| TeamBeInvite ModeEnum |
getTeamBeInviteMode() | 获取群被邀请模式：被邀请人的同意方式 |
| TeamExtension UpdateModeEnum |
getTeamExtension UpdateMode() |
获取群资料扩展字段修改模式：谁可以修改群自定义属性(扩展字段) |
| TeamInviteModeEnum | getTeamInviteMode() | 获取群邀请模式：谁可以邀请他人入群 |
| TeamUpdateModeEnum | getTeamUpdateMode() | 获取群资料修改模式：谁可以修改群资料 |
| TeamTypeEnum | getType() | 获取群组类型 |
| VerifyTypeEnum | getVerifyType() | 获取申请加入群组时的验证类型 |
| boolean | isAllMute() | 是否群全员禁言 |
| TeamAllMuteModeEnum | getMuteMode() | 获取全员禁言模式 |
| boolean | isMyTeam() | 获取自己是否在这个群里 |
| boolean | mute() | 获取这个群收到新消息时要不要提醒的设置，废弃，使用getMessageNotifyType()替代 |
| TeamMessageNotifyTypeEnum | getMessageNotifyType() | 获取当前账号在此群收到消息之后提醒的类型 |
| void | setExtension(extension) | 设置群组扩展配置。 |
- 示例
异步请求示例：
NIMClient.getService(TeamService.class).queryTeamList().setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// 获取成功，teams为加入的所有群组
}
@Override
public void onFailed(int i) {
// 获取失败，具体错误码见i参数
}
@Override
public void onException(Throwable throwable) {
// 获取异常
}
});同步请求示例：
// teams为加入的所有群组
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListBlock();注意：这里获取的是所有我加入的群列表（退群、被移除群后，将不在返回列表中），如果需要自己退群或者被移出群的群资料，请使用下面的 queryTeam 接口。
2. 根据类型获取我加入的群组
- API 原型
异步版本:
/**
* 获取自己加入的指定类型群（讨论组/高级群）列表
*
* @param type 群类型
* @return 可以设置回调函数，如果成功，参数为加入的指定类型群列表
*/
InvocationFuture<List<Team>> queryTeamListByType(TeamTypeEnum type);同步版本:
/**
* 获取自己加入的指定类型群（讨论组/高级群）列表（同步版本）
*
* @param type 群类型
* @return 加入的指定类型群列表
*/
public List<Team> queryTeamListByTypeBlock(TeamTypeEnum type);- 参数说明
| TeamTypeEnum属性 | 说明 |
|---|---|
| Advanced | 高级群，有完善的权限管理功能 |
| Normal | 讨论组，仅具有基本的权限管理功能，所有人都能加入， 仅拥有者可以踢人 |
- 示例
异步版本示例：
// 以讨论组为例
NIMClient.getService(TeamService.class).queryTeamListByType(TeamTypeEnum.Normal).setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// 成功
}
@Override
public void onFailed(int i) {
// 失败
}
@Override
public void onException(Throwable throwable) {
// 错误
}
});同步版本示例:
// 以高级群为例
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListByTypeBlock(TeamTypeEnum.Advanced)创建群组
网易云通信群组分为两类：普通群和高级群，两种群组的消息功能都是相同的，区别在于管理功能。普通群所有人都可以拉人入群，除群主外，其他人都不能踢人；固定群则拥有完善的成员权限体系及管理功能。创建群的接口相同，传入不同的类型参数即可。
API 原型
/** * 创建一个群组 * * @return InvocationFuture 可以设置回调函数，如果成功，参数为创建的群组资料 */ InvocationFuture<CreateTeamResult> createTeam(Map<TeamFieldEnum, Serializable> fields, TeamTypeEnum type, String postscript, List<String> members);参数说明
| 参数 | 说明 |
|---|---|
| fields | 群组预设资料, key为数据字段，value对应的值， 该值类型必须和field中定义的fieldType一致。 |
| type | 要创建的群组类型 |
| postscript | 邀请入群的附言。如果是创建临时群，该参数无效 |
| members | 邀请加入的成员帐号列表 |
CreateTeamResult 说明
| 参数 | 说明 |
|---|---|
| team | 创建成功后返回的team 对象 |
| failedInviteAccounts | 被邀请成员中群组数量已达上限的成员列表 |
- 示例
// 群组类型
TeamTypeEnum type = TeamTypeEnum.Advanced;
// 创建时可以预设群组的一些相关属性，如果是普通群，仅群名有效。
// fields 中，key 为数据字段，value 对对应的值，该值类型必须和 field 中定义的 fieldType 一致
HashMap<TeamFieldEnum, Serializable> fields = new HashMap<TeamFieldEnum, Serializable>();
fields.put(TeamFieldEnum.Name, teamName);
fields.put(TeamFieldEnum.Introduce, teamIntroduce);
fields.put(TeamFieldEnum.VerifyType, verifyType);
NIMClient.getService(TeamService.class).createTeam(fields, type, "", accounts)
.setCallback(new RequestCallback<Team> { ... });申请加入群组
- API 原型
/**
* 用户申请加入群。
*
* @param tid 申请加入的群ID
* @param postscript 申请附言
* @return InvocationFuture 可以设置回调函数，如果成功，参数为群资料
*/
InvocationFuture<Team> applyJoinTeam(String tid, String postscript);- 参数说明
| 参数 | 说明 |
|---|---|
| tid | 申请加入的群ID |
| postscript | 申请附言 |
- 示例
NIMClient.getService(TeamService.class).applyJoinTeam(team.getId(), null).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// 申请成功, 等待验证入群
}
@Override
public void onFailed(int code) {
// 申请失败
}
@Override
public void onException(Throwable exception) {
// error
}
});- 特殊错误码说明
| 错误码 | 说明 |
|---|---|
| 808 | 申请已发出 |
| 809 | 已经在群里 |
验证入群申请
用户发出申请后，所有管理员都会收到一条系统通知，类型为 SystemMessageType#TeamApply，具体参数解释请参考系统通知章节。管理员可选择同意或拒绝。
1. 同意入群申请
仅管理员和拥有者有此权限。如果同意入群申请，群内所有成员(包括申请者)都会收到一条消息类型为 notification 的通知消息，附件类型为 MemberChangeAttachment。具体参数说明见消息收发章节。
- API 原型
/**
* 通过用户的入群申请
* 仅管理员和拥有者有此权限
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> passApply(String teamId, String account);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| account | 申请入群的用户ID |
- 示例
// teamId为申请加入的群组id， account为申请入群的用户id
NIMClient.getService(TeamService.class).passApply(teamId, account).setCallback(...);2. 拒绝入群申请
仅管理员和拥有者有此权限。如果拒绝入群申请，申请者会收到一条系统通知，类型为 SystemMessageType#RejectTeamApply。具体参数说明见系统通知章节。
- API 原型
/**
* 拒绝用户的入群申请
* 仅管理员和拥有者有此权限
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> rejectApply(String teamId, String account, String reason);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| account | 申请入群的用户ID |
| reason | 拒绝理由，选填 |
- 示例
// teamId为申请加入的群组id， account为申请入群的用户id
NIMClient.getService(TeamService.class).rejectApply(teamId, account, "您已被拒绝").setCallback(...);说明：任意一管理员操作后，其他管理员再操作都会失败。
邀请加入群组
普通群所有人都可以拉人入群，SDK 2.4.0之前版本高级群仅管理员和拥有者可以邀请人入群， SDK 2.4.0及以后版本高级群在创建时可以设置群邀请模式，支持仅管理员或者所有人均可拉人入群。如果在被邀请成员中存在成员的群组数量已达上限，则会返回这部分失败成员的账号。
- API 原型
/**
* 添加成员
*
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<List<String>> addMembers(String teamId, List<String> accounts);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群组ID |
| accounts | 待加入的群成员帐号列表 |
- 示例
NIMClient.getService(TeamService.class).addMembers(teamId, accounts)
.setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 返回onSuccess，表示拉人不需要对方同意，且对方已经入群成功了
}
@Override
public void onFailed(int code) {
// 返回onFailed，并且返回码为810，表示发出邀请成功了，但是还需要对方同意
}
@Override
public void onException(Throwable exception) {
...
}
});- 特殊错误码说明
| 错误码 | 说明 |
|---|---|
| 810 | 高级群邀请人的情况下，发出邀请成功了，但是还需要对方同意 |
说明：被邀请的人会收到一条系统通知 (SystemMessage)，类型为 SystemMessageType#TeamInvite。用户接受该邀请后，才真正入群。可以通过 SystemMessage#getAttachObject 获取服务器设置的扩展字段，类型为TeamInviteNotify。
用户入群（普通群被拉人，高级群接受邀请）后，在收到之后的第一条消息时，群内所有成员（包括入群者）会收到一条入群消息，附件类型为 MemberChangeAttachment。若通知类型为NotificationType#InviteMember，可以通过 MemberChangeAttachment#getExtension 获取服务器设置的扩展字段。
验证入群邀请
收到入群邀请后，用户可在系统通知中看到该邀请，并选择接受或拒绝。接受邀请后，用户真正入群。如果拒绝邀请，邀请该用户的管理员会收到一条系统通知，类型为 SystemMessageType#DeclineTeamInvite。
1. 接受入群邀请
- API 原型
/**
* 接受别人的入群邀请
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> acceptInvite(String teamId, String inviter);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| inviter | 邀请我的用户帐号 |
- 示例
NIMClient.getService(TeamService.class).acceptInvite(teamId, inviter).setCallback(...);2. 拒绝入群邀请
- API 原型
/**
* 拒绝别人的入群邀请通知
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> declineInvite(String teamId, String inviter, String reason);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| inviter | 邀请我的用户帐号 |
| reason | 拒绝理由，选填 |
- 示例
NIMClient.getService(TeamService.class).declineInvite(teamId, inviter, "").setCallback(callback);踢人出群
普通群仅拥有者可以踢人，高级群拥有者和管理员可以踢人，且管理员不能踢拥有者和其他管理员。踢人后，群内所有成员(包括被踢者)会收到一条消息类型为 notification 的 IMMessage，类型为 NotificationType#KickMember, 附件类型为 MemberChangeAttachment。可以通过 MemberChangeAttachment#getExtension 获取服务器设置的扩展字段。
- API 原型
/**
* 移除成员，只有创建者有此权限
*
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> removeMember(String teamId, String member);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| member | 被踢出的成员帐号 |
- 示例
// teamId表示群ID，account表示被踢出的成员帐号
NIMClient.getService(TeamService.class).removeMember(teamId, account).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});主动退群
普通群群主可以退群，若退群，该群没有群主。高级群除群主外，其他用户均可以主动退群。退群后，群内所有成员(包括退出者)会收到一条消息类型为 notification 的 IMMessage，附件类型为 MemberChangeAttachment。
- API 原型
/**
* 退出群
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> quitTeam(String teamId);- 示例
NIMClient.getService(TeamService.class).quitTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 退群成功
}
@Override
public void onFailed(int code) {
// 退群失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});转让群组
高级群拥有者可以将群的拥有者权限转给群内的其他成员，转移后，被转让者变为新的拥有者，原拥有者变为普通成员。原拥有者还可以选择在转让的同时，直接退出该群。
- API 原型
/**
* 拥有者将群的拥有者权限转给另外一个人，转移后，另外一个人成为拥有者。
* 原拥有者变成普通成员。若参数quit为true，原拥有者直接退出该群。
*
* @return InvocationFuture 可以设置回调函数，如果成功，视参数quit值：
* quit为false：参数仅包含原拥有着和当前拥有者的(即操作者和account)，权限已被更新。
* quit为true: 参数为空。
*/
InvocationFuture<List<TeamMember>> transferTeam(String tid, String account, boolean quit);- 参数说明
| 参数 | 说明 |
|---|---|
| tid | 群ID |
| account | 新任拥有者的用户帐号 |
| quit | 转移时是否要同时退出该群 |
| 返回值 | 说明 |
|---|---|
| InvocationFuture | 可以设置回调函数，如果成功，视参数quit值： quit为false：参数仅包含原拥有着和当前拥有者的(即操作者和account)，权限已被更新。 quit为true: 参数为空 |
| 返回值 | TeamMember属性 | 说明 |
|---|---|---|
| String | getAccount() | 群成员帐号 |
| Map | getExtension() | 获取扩展字段 |
| long | getJoinTime() | 获取群成员入群时间 |
| String | getTeamNick() | 获取该用户在这个群内的群昵称 |
| String | getTid() | 获取所在群ID |
| TeamMemberType | getType() | 群成员类型 |
| boolean | isInTeam() | 是否该用户是否在这个群中 |
| boolean | isMute() | 是否被禁言 |
- 示例
// false表示群主转让后不退群
NIMClient.getService(TeamService.class).transferTeam(teamId, account, false)
.setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// 群转移成功
}
@Override
public void onFailed(int code) {
// 群转移失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});解散群组
仅群主有这个权限。
- API 原型
/**
* 解散群，只有群主有此权限
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> dismissTeam(String teamId);- 示例
NIMClient.getService(TeamService.class).dismissTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 解散群成功
}
@Override
public void onFailed(int code) {
// 解散群失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});获取群组成员
由于群组成员数据比较大，且除了进入群组成员列表界面外，其他地方均不需要群组成员列表的数据，因此 SDK 不会在登录时同步群组成员数据，而是按照按需获取的原则，当上层主动调用获取指定群的群组成员列表时，才判断是否需要同步。
群成员资料 SDK 本地存储说明： 当自己退群、或者被移出群时，本地数据库会继续保留这个群成员资料，只是设置了无效标记，此时依然可以通过 queryTeamMember 查出来该群成员资料，只是 isInTeam 将返回 false 。
1. 获取群组所有成员
- API 原型
/**
* 获取指定群的成员信息列表. <br>
* 该操作有可能只是从本地数据库读取缓存数据，也有可能会从服务器同步新的数据, 因此耗时可能会比较长。
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数，如果成功，参数为群的成员信息列表
*/
InvocationFuture<List<TeamMember>> queryMemberList(String teamId);- 示例
NIMClient.getService(TeamService.class).queryMemberList(teamId).setCallback(new RequestCallbackWrapper<List<TeamMember>>() {
@Override
public void onResult(int code, final List<TeamMember> members, Throwable exception) {
...
}
});2. 根据群 ID 和成员帐号获取群成员
如果本地群成员资料已过期， SDK 会去服务器获取最新的。
- API 原型
异步版本：
/**
* 查询群成员资料。如果本地群成员资料已过期会去服务器获取最新的。
*
* @param teamId 群ID
* @param account 群成员帐号
* @return InvocationFuture 可以设置回调函数，如果成功，参数为该群成员信息
*/
InvocationFuture<TeamMember> queryTeamMember(String teamId, String account);同步版本（仅查询本地群资料）：
/**
* 查询群成员资料。（同步版本）仅查询本地群资料
*
* @param teamId 群ID
* @param account 群成员帐号
* @return 群成员信息
*/
TeamMember queryTeamMemberBlock(String teamId, String account);- 示例
异步版本示例:
NIMClient.getService(TeamService.class).queryTeamMember(teamId, account).setCallback(new RequestCallbackWrapper<TeamMember>() {
@Override
public void onResult(int code, TeamMember member, Throwable exception) {
...
}
});同步版本示例：
TeamMember member = NIMClient.getService(TeamService.class).queryTeamMemberBlock(teamId, account);提升管理员
高级群中，群主可以增加管理员。操作完成后，群内所有成员都会收到一条消息类型为 notification 的 IMMessage，附件类型为 MemberChangeAttachment。
- API 原型
/**
* 拥有者添加管理员
* 仅拥有者有此权限
*
* @param teamId 群ID
* @param accounts 待提升为管理员的用户帐号列表
* @return InvocationFuture 可以设置回调函数,如果成功，参数为新增的群管理员列表
*/
InvocationFuture<List<TeamMember>> addManagers(String teamId, List<String> accounts);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| accounts | 待提升为管理员的用户帐号列表 |
| 返回值 | 说明 |
|---|---|
| InvocationFuture | 可以设置回调函数，如果成功，参数为被撤销的群成员列表 (权限已被降为Normal)。 |
- 示例
// teamId 操作的群id， accountList为待提升为管理员的用户帐号列表
NIMClient.getService(TeamService.class).addManagers(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> managers) {
// 添加群管理员成功
}
@Override
public void onFailed(int code) {
// 添加群管理员失败
}
@Override
public void onException(Throwable exception) {
// 错误
});移除管理员
高级群中，群主可以移除管理员。操作完成后，群内所有成员都会收到一条消息类型为 notification 的 IMMessage，附件类型为 MemberChangeAttachment。
- API 原型
/**
* 拥有者撤销管理员权限
* 仅拥有者有此权限
*
* @param teamId 群ID
* @param managers 待撤销的管理员的帐号列表
* @return InvocationFuture 可以设置回调函数，如果成功，参数为被撤销的群成员列表(权限已被降为Normal)。
*/
InvocationFuture<List<TeamMember>> removeManagers(String teamId, List<String> managers);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| managers | 待撤销的管理员的帐号列表 |
| 返回值 | 说明 |
|---|---|
| InvocationFuture | 可以设置回调函数，如果成功，参数为被撤销的群成员列表 (权限已被降为Normal)。 |
- 示例
// teamid为群id， accountList为待撤销的管理员的账号列表
NIMClient.getService(TeamService.class).removeManagers(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// 移除群管理员成功
}
@Override
public void onFailed(int code) {
// 移除群管理员失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});群成员禁言
支持管理员和群主对普通成员的禁言、解除禁言操作。
- API 原型
/**
* 禁言、解除禁言
*
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> muteTeamMember(String teamId, String account, boolean mute);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群组ID |
| account | 被禁言、被解除禁言的账号 |
| mute | true表示禁言，false表示解除禁言 |
- 示例
// 以禁言为例
NIMClient.getService(TeamService.class).muteTeamMember(teamId, account, true).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});群整体禁言
将整个群禁言，该操作仅群主或者管理员有权限。禁言操作成功之后，会回调群更新接口，影响方法 Team#getMuteMode 和 Team#isAllMute
- API 原型
/**
* 对整个群禁言、解除禁言，对普通成员生效，只有群组、管理员有权限
*
* @param teamId 群组 ID
* @param mute true表示禁言，false表示解除禁言
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> muteAllTeamMember(String teamId, boolean mute);- 示例
// members表示被禁言的成员列表
NIMClient.getService(TeamService.class).muteAllTeamMember(teamId, true));查询被禁言群成员
该操作只返回被禁言的用户
- API 原型
/**
* 查询被禁言群成员列表
* 该操作，只返回调用TeamService#muteTeamMember(String, String, boolean) 禁言的用户。
*
* @param teamId 群ID
* @return 群成员信息列表
*/
List<TeamMember> queryMutedTeamMembers(String teamId);- 示例
// members表示被禁言的成员列表
List<TeamMember> members = NIMClient.getService(TeamService.class).queryMutedTeamMembers(teamId);群组资料管理
查询群组资料
1. 从本地数据库中查询群资料
如果本地没有群组资料，则去服务器查询。如果自己不在这个群中，该接口返回的可能是过期资料，如需最新的，请调用 searchTeam 接口去服务器查询。 此外 queryTeam 接口也有同步版本： queryTeamBlock 。
- API 原型
异步版本：
/**
* 查询群资料，如果本地没有群组资料，则去服务器查询。
* 如果自己不在这个群中，该接口返回的可能是过期资料，如需最新的，请调用{@link #searchTeam(String)}接口
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数，如果成功，参数为群资料
*/
InvocationFuture<Team> queryTeam(String teamId);同步版本：
/**
* 查询群资料（仅查询本地，不会去服务器请求)
* 如果自己不在这个群中，该接口返回的可能是过期资料，如需最新的，请调用{@link #searchTeam(String)}接口
*
* @param teamId 群ID
* @return 群资料
*/
Team queryTeamBlock(String teamId);注意: 同步版本的查询群资料，仅查询本地，不会去服务器请求
- 示例
异步接口示例:
NIMClient.getService(TeamService.class).queryTeam(teamId).setCallback(new RequestCallbackWrapper<Team>() {
@Override
public void onResult(int code, Team t, Throwable exception) {
if (code == ResponseCode.RES_SUCCESS) {
// 成功
} else {
// 失败，错误码见code
}
if (exception != null) {
// error
}
}
});同步接口示例：
// teamId 为想要查询的群组 ID
Team team = NIMClient.getService(TeamService.class).queryTeamBlock(teamId);2. 从服务器上查询群资料
用户可以直接从服务器上查询群资料
- API 原型
/**
* 从服务器上查询群资料信息
*
* @param teamId 群ID
* @return
*/
InvocationFuture<Team> searchTeam(String teamId);- 示例
// teamId为想要查询的群组ID
NIMClient.getService(TeamService.class).searchTeam(teamId).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// 查询成功，获得群组资料
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});- 特殊错误码说明
| 错误码 | 说明 |
|---|---|
| 803 | 查询的群id不存在 |
群资料 SDK 本地存储说明：
1. 解散群、退群或者被移出群时，本地数据库会继续保留这个群资料，只是设置了无效标记，此时依然可以通过 queryTeam 查出来该群资料，只是 isMyTeam 返回 false 。 如果用户手动清空全部本地数据，下次登录同步时，服务器不会将无效的群资料同步过来，将无法取得已退出群的群资料。
2. 群解散后，通过 searchTeam 接口从服务器查询将返回 null 。
编辑群组资料
1. 单个群属性更新
每次仅修改群的一个属性，可修改的属性查看 TeamFieldEnum ，注意： 其中的 Ext_Server 群服务器扩展字段，仅限服务端修改。
更新的value值，对应的数据类型，同样查看 TeamFieldEnum 。例如：群名 Name(ITeamService.TinfoTag.NAME, String.class)，表示 value 值的数据类型为 String。验证类型 VerifyType(ITeamService.TinfoTag.JOIN_MODE, VerifyTypeEnum.class)，表示 value 值的数据类型为VerifyTypeEnum。
| TeamFieldEnum属性 | 说明 | 数据类型 |
|---|---|---|
| AllMute | 群禁言（群全员禁言），该字段只读，使用“群资料更新”接口更新该字段无效。 | TeamAllMuteModeEnum |
| Announcement | 群公告 | String |
| BeInviteMode | 群被邀请模式：被邀请人的同意方式 | TeamBeInviteModeEnum |
| Ext_Server | 群扩展字段（仅服务端能够修改） | String |
| Extension | 群扩展字段（客户端自定义信息） | String |
| ICON | 群头像 | String |
| Introduce | 群简介 | String |
| InviteMode | 群邀请模式：谁可以邀请他人入群 | TeamInviteModeEnum |
| Name | 群名 | String |
| TeamExtensionUpdateMode | 群资料扩展字段修改模式： 谁可以修改群自定义属性(扩展字段) |
TeamExtensionUpdateModeEnum |
| TeamUpdateMode | 群资料修改模式：谁可以修改群资料 | TeamUpdateModeEnum |
| undefined | 未定义的域 | |
| VerifyType | 申请加入群组的验证模式 | VerifyTypeEnum |
| MaxMemberCount | 指定创建群组的最大群成员数量 | int |
修改后，群内所有成员会收到一条消息类型为 notification 的 IMMessage，带有一个消息附件，类型为 UpdateTeamAttachment。如果注册了群组资料变化观察者，观察者也会收到通知，见监听群组资料变化。
- API 原型
/**
* 更新群组资料
*
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> updateTeam(String teamId, TeamFieldEnum field, Serializable value);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| field | 待更新的域 |
| value | 待更新的域的新值 该值类型必须和field中定义的fieldType一致 |
- 示例
以群公告为例
String announcement = "这是更新的群公告";
NIMClient.getService(TeamService.class).updateTeam(teamId, TeamFieldEnum.Announcement, announcement).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});注意: 更新群头像请注意: 需要先调用
NosService#upload方法，将头像图片成功上传到 nos。再将 nos 的 url 地址更新到群资料。
2. 批量更新群组资料
- API 原型
/**
* 批量更新群组资料，可一次性更新多个字段的值。
*
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> updateTeamFields(String teamId, Map<TeamFieldEnum, Serializable> fields);- 参数说明
| 参数 | 说明 |
|---|---|
| teamId | 群ID |
| fields | 待更新的所有字段的新的资料，其中值类型必须和field中定义的fieldType一致 |
- 示例
// 以名字，介绍，公告为例
Map<TeamFieldEnum, Serializable> fieldsMap = new HashMap<>();
fieldsMap.put(TeamFieldEnum.Name, "新的名称");
fieldsMap.put(TeamFieldEnum.Introduce, "新的介绍");
fieldsMap.put(TeamFieldEnum.Announcement, "新的公告");
NIMClient.getService(TeamService.class).updateTeamFields(teamId,
fieldsMap).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void aVoid) {
// 成功
}
@Override
public void onFailed(int i) {
// 失败
}
@Override
public void onException(Throwable throwable) {
// 错误
}
});监听群组资料变化
由于获取群组资料需要跨进程异步调用，开发者最好能在第三方 APP 中做好群组资料缓存，查询群组资料时都从本地缓存中访问。在群组资料有变化时，SDK 会告诉注册的观察者，此时，第三方 APP 可更新缓存，并刷新界面。
1. 监听群资料变化
- API 原型
/**
* 群资料变动观察者通知。新建群和群更新的通知都通过该接口传递
* @param observer 观察者, 参数为有更新的群资料列表
* @param register true为注册，false为注销
*/
public void observeTeamUpdate(Observer<List<Team>> observer, boolean register);- 参数说明
| 返回值 | Team接口 | 说明 |
|---|---|---|
| String | getAnnouncement() | 获取群组公告 |
| long | getCreateTime() | 获取群组的创建时间 |
| String | getCreator() | 获取创建群组的用户帐号 |
| String | getExtension() | 获取群组扩展配置 |
| String | getExtServer() | 获取服务器设置的扩展配置 |
| String | getIcon() | 获取群头像 |
| String | getId() | 获取群组ID |
| String | getIntroduce() | 获取群组简介 |
| int | getMemberCount() | 获取群组的总成员数 |
| int | getMemberLimit() | 获取群组的成员人数上限 |
| String | getName() | 获取群组名称 |
| TeamBeInviteModeEnum | getTeamBeInviteMode() | 获取群被邀请模式：被邀请人的同意方式 |
| TeamExtensionUpdateModeEnum | getTeamExtensionUpdateMode() | 获取群资料扩展字段修改模式：谁可以修改群自定义属性(扩展字段) |
| TeamInviteModeEnum | getTeamInviteMode() | 获取群邀请模式：谁可以邀请他人入群 |
| TeamUpdateModeEnum | getTeamUpdateMode() | 获取群资料修改模式：谁可以修改群资料 |
| TeamTypeEnum | getType() | 获取群组类型 |
| VerifyTypeEnum | getVerifyType() | 获取申请加入群组时的验证类型 |
| boolean | isAllMute() | 是否群全员禁言 |
| boolean | isMyTeam() | 获取自己是否在这个群里 |
| boolean | mute() | 获取这个群收到新消息时要不要提醒的设置，废弃，使用getMessageNotifyType()替代 |
| TeamMessageNotifyTypeEnum | getMessageNotifyType() | 获取当前账号在此群收到消息之后提醒的类型 |
| void | setExtension(String extension) | 设置群组扩展配置 |
- 示例
// 创建群组资料变动观察者
Observer<List<Team>> teamUpdateObserver = new Observer<List<Team>>() {
@Override
public void onEvent(List<Team> teams) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeTeamUpdate(teamUpdateObserver, register);2. 监听移除群的变化
移除成功后，Team#isMyTeam 返回 false。
- API 原型
/**
* 移除群的观察者通知。自己退群，群被解散，自己被踢出群时，会收到该通知
* @param observer 观察者, 参数为被移除的群资料，此时群的isMyTeam接口返回false
* @param register true为注册，false为注销
*/
public void observeTeamRemove(Observer<Team> observer, boolean register);- 示例
// 创建群组被移除的观察者。在退群，被踢，群被解散时会收到该通知。
Observer<Team> teamRemoveObserver = new Observer<Team>() {
@Override
public void onEvent(Team team) {
// 由于界面上可能仍需要显示群组名等信息，因此参数中会返回 Team 对象。
// 该对象的 isMyTeam 接口返回为 false。
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeTeamRemove(teamRemoveObserver, register);修改群成员群昵称
普通群不支持修改成员的群昵称。
对于高级群，群主和管理员修改群内其他成员的群昵称，仅群主和管理员拥有权限。
群主可以修改所有人的群昵称。管理员只能修改普通群成员的群昵称。
- API 原型
/**
* 群组管理员修改群内其他成员的群昵称。
* 仅群管理员和拥有者有此权限
*
* @param teamId 所在群组ID
* @param account 要修改的群成员帐号
* @param nick 新的群昵称
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> updateMemberNick(String teamId, String account, String nick);- 示例
// teamId表示所在群组ID，account表示要修改的群成员帐号，nickname表示新的群昵称
NIMClient.getService(TeamService.class).updateMemberNick(teamId, account, nickname).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});修改自己的群昵称
普通群不支持修改自己的群昵称。
- API 原型
/**
* 修改自己的群昵称
*
* @param teamId 所在群组ID
* @param nick 新的群昵称
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> updateMyTeamNick(String teamId, String nick);- 示例
// test为修改后自己的群昵称
NIMClient.getService(TeamService.class).updateMyTeamNick(teamId, "test")修改自己的群成员扩展字段
修改后，群成员会收到群成员资料变更通知
- API 原型
/**
* 修改自己的群成员扩展字段（自定义属性）
*
* @param teamId 所在群组ID
* @param extension 新的扩展字段（自定义属性）
* @return InvocationFuture 可以设置回调函数，监听操作结果
*/
InvocationFuture<Void> updateMyMemberExtension(String teamId, Map<String, Object> extension);- 示例
Map<String, Object> extension = new HashMap<>();
extension.put("ext","newExt");
NIMClient.getService(TeamService.class).updateMyMemberExtension(teamId, ext)监听群成员资料变化
由于获取群成员资料需要跨进程异步调用，开发者最好能在第三方 APP 中做好群成员资料缓存，查询群成员资料时都从本地缓存中访问。在群成员资料有变化时，SDK 会告诉注册的观察者，此时，第三方 APP 可更新缓存，并刷新界面。
1. 监听群成员资料变化
- API 原型
/**
* 群成员资料变化观察者通知。
* 上层APP如果管理了群成员资料的缓存，可通过此接口更新缓存。
* @param observer 观察者, 参数为有更新的群成员资料列表
* @param register true为注册，false为注销
*/
public void observeMemberUpdate(Observer<List<TeamMember>> observer, boolean register);- 示例
// 群成员资料变化观察者通知。群组添加新成员，成员资料变化会收到该通知。
// 返回的参数为有更新的群成员资料列表。
Observer<List<TeamMember>> memberUpdateObserver = new Observer<List<TeamMember>>() {
@Override
public void onEvent(List<TeamMember> members) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeMemberUpdate(memberUpdateObserver, register);2. 监听移除群成员的变化
- API 原型
/**
* 移除群成员的观察者通知。
* @param observer 观察者, 参数为被移除的群成员
* @param register true为注册，false为注销
*/
public void observeMemberRemove(Observer<TeamMember> observer, boolean register);- 示例
// 移除群成员的观察者通知。
private Observer<TeamMember> memberRemoveObserver = new Observer<TeamMember>() {
@Override
public void onEvent(TeamMember member) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeMemberRemove(memberRemoveObserver, register);