群组功能-Android开发集成-SDK开发集成-IM即时通讯-网易云信开发文档

群组功能

群组功能概述

网易云通信 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 forcePushList)	设置强推列表，填 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);

/**
 * 添加成员并设置自定义字段
 *
 * @return InvocationFuture 可以设置回调函数，监听操作结果
 */
InvocationFuture<List<String>> addMembersEx(String teamId, List<String> accounts, String msg, String customInfo);

参数说明

参数	说明
teamId	群组ID
accounts	待加入的群成员帐号列表
msg	邀请附言，不需要的话设置为空
customInfo	自定义扩展字段，不需要的话设置为空

示例

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);

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志