社群成员管理
2026-05-22
功能简介
ZIM SDK 提供了完整的社群成员管理能力，支持以下功能：
- 邀请用户加入社群
- 踢出社群成员
- 更新成员角色
- 转让社群所有权
- 查询社群成员列表
- 查询指定成员信息
- 设置成员禁言状态
- 监听成员状态与信息变更
前提条件
- 请参考 实现基本消息收发 完成 ZIM SDK 获取、初始化和用户登录。
- 请参考 使用 Token 鉴权 实现用户鉴权登录。
- 社群功能需要 ZIM SDK 3.0.0 及以上版本。
- 社群功能为旗舰版功能，使用前请联系 ZEGO 技术支持开通。
- 社群功能的 Token 生成方式与其他 ZIM 功能一致，无需额外权限声明。
邀请用户加入社群
调用 inviteUsersIntoCommunity 接口，批量邀请用户加入社群。邀请无需对方同意，被邀请用户直接成为社群成员。被邀请用户必须已在系统中注册。 单次调用接口最多一次邀请 100 名用户加入社群。
操作失败的用户信息将通过 errorUserList 返回。
import im.zego.zim.ZIM;
import im.zego.zim.callback.ZIMCommunityUsersInvitedCallback;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.entity.ZIMErrorUserInfo;
import im.zego.zim.enums.ZIMErrorCode;
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("user_1");
userIDs.add("user_2");
zim.inviteUsersIntoCommunity(userIDs, communityID, new ZIMCommunityUsersInvitedCallback() {
@Override
public void onCommunityUsersInvited(String communityID, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// 邀请完成，errorUserList 中列出邀请失败的用户信息
}
}
});常见错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 6001004 | 社群不存在 | 确认 communityID 是否正确 |
| 6001005 | 用户不在社群中 | 仅在特定场景出现，确认用户状态 |
| 6001007 | 社群权限错误 | 确认当前用户是否有邀请权限 |
踢出社群成员
调用 kickCommunityMembers 接口，批量将指定成员从社群中移除。 单次调用接口最多一次从社群踢出 100 名用户。
注意
仅社群所有者和管理员可调用此接口。
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("user_1");
userIDs.add("user_2");
zim.kickCommunityMembers(userIDs, communityID, new ZIMCommunityMembersKickedCallback() {
@Override
public void onCommunityMembersKicked(String communityID, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// 踢出完成，errorUserList 中列出操作失败的用户
}
}
});更新社群成员角色
调用 updateCommunityMemberRole 接口，修改指定成员在社群中的角色，如将普通成员设置为管理员。
注意
仅社群所有者可调用此接口。
社群角色 1 为社群群主，2 为社群管理员，3 为社群普通成员。
//ZIMCommunityMemberRole.OWNER = 社群群主，ZIMCommunityMemberRole.ADMIN = 社群管理员，ZIMCommunityMemberRole.MEMBER = 社群普通成员
zim.updateCommunityMemberRole(ZIMCommunityMemberRole.ADMIN, "target_user_id", communityID,
new ZIMCommunityMemberRoleUpdatedCallback() {
@Override
public void onCommunityMemberRoleUpdated(String communityID, String forUserID, ZIMCommunityMemberRole memberRole, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// 角色更新成功
}
}
});转让社群所有权
调用 transferCommunityOwner 接口，将当前社群的所有权转让给社群内的其他成员。转让后，原所有者将成为普通成员。
注意
仅社群所有者可调用此接口。
zim.transferCommunityOwner("new_owner_user_id", communityID,
new ZIMCommunityOwnerTransferredCallback() {
@Override
public void onCommunityOwnerTransferred(String communityID, String toUserID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// 转让成功
}
}
});查询社群成员列表
调用 queryCommunityMemberList 接口，分页拉取指定社群的成员列表。
分页规则与查询社群列表一致：首次将 config.nextFlag 设为 0，后续将返回的 nextFlag 传入下次请求，直到 nextFlag 返回 0 为止。
ZIMCommunityMemberListQueryConfig config = new ZIMCommunityMemberListQueryConfig();
config.setNextFlag(0); // 首次查询设为 0
zim.queryCommunityMemberList(communityID, 100, config, new ZIMCommunityMemberListQueriedCallback() {
@Override
public void onCommunityMemberListQueried(String communityID, ArrayList<ZIMCommunityMemberInfo> memberList, long nextFlag, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// memberList 为当前页成员列表
}
}
});查询指定成员信息
调用 queryCommunityMembers 接口，批量查询指定用户在社群中的成员信息，包括角色、禁言状态等。
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("user_1");
userIDs.add("user_2");
zim.queryCommunityMembers(userIDs, communityID, new ZIMCommunityMembersQueriedCallback() {
@Override
public void onCommunityMembersQueried(String communityID, ArrayList<ZIMCommunityMemberInfo> memberList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// memberList 为查询到的成员信息
}
}
});设置成员禁言
调用 muteCommunityMembers 接口，批量设置指定成员在社群内指定频道中的禁言状态。禁言配置通过 ZIMCommunityMemberMuteConfig 传入。
| 配置字段 | 说明 |
|---|---|
channelID | 指定禁言生效的频道 ID。留空则对所有频道生效。 |
duration | 禁言时长（秒），取值范围 1-2592001（约 30 天），或 -1 表示永久禁言。 |
注意
仅社群所有者和管理员可调用此接口。
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("user_1");
userIDs.add("user_2");
ZIMCommunityMemberMuteConfig config = new ZIMCommunityMemberMuteConfig();
config.setDuration(3600); // 禁言 1 小时；-1 为永久禁言
config.setChannelID("channel_001"); // 指定频道；留空则对所有频道生效
// isMute = true 为禁言，false 为解除禁言
zim.muteCommunityMembers(true, userIDs, communityID, config,
new ZIMCommunityMembersMutedCallback() {
@Override
public void onCommunityMembersMuted(String communityID, String channelID, boolean isMute, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// 禁言设置成功
}
}
});监听成员变更
成员状态变化
当成员加入或离开社群时，SDK 会触发 onCommunityMemberStateChanged 回调。通过 updateInfo.getState() 可判断成员是进入（ENTERED）还是退出（EXITED）。
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityMemberStateChanged(ZIM zim, ZIMCommunityMemberStateChangedEventResult result) {
for (ZIMCommunityMemberStateChangeInfo updateInfo : result.getUpdateInfoList()) {
if (updateInfo.getState() == ZIMCommunityMemberChangeState.ENTERED) {
// 成员加入社群
} else if (updateInfo.getState() == ZIMCommunityMemberChangeState.EXITED) {
// 成员离开社群
}
}
}
});成员信息更新
当社群成员的昵称、角色或禁言状态等信息发生变化时，SDK 会触发 onCommunityMemberInfoUpdated 回调。
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityMemberInfoUpdated(ZIM zim, ZIMCommunityMemberInfoUpdatedEventResult result) {
for (ZIMCommunityMemberInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
ZIMCommunityMemberInfo memberInfo = updateInfo.getMemberInfo();
// memberInfo.memberRole：成员角色
// memberInfo.muteInfo：禁言信息
// memberInfo.enterInfo：成员入群信息
}
}
});