logo文档中心
登录/注册控制台
文档
ZIM 客户端 API
ZPNs 客户端 API
ZIM Audio 客户端 API
服务端 API
即时通讯
Android: Java
产品简介
概述
计费说明
基本概念介绍
客户端 SDK
下载
发布日志
升级指南
错误码
快速开始
跑通示例代码
实现基本消息收发
连接至 ZEGO 文档 MCP 服务link
功能指引
用户
房间
群组
消息
会话
社群
缓存管理
内容审核
呼叫邀请
离线推送
ZIM Audio
最佳实践
迁移方案
常见问题link
当前页

社群管理

2026-05-22

功能简介

社群产品上一般会有 "社群-频道-话题"（对应 Discord 的 Server-Channel-Thread）的三层社交组织结构。更详细介绍可查看 功能概述。

ZIM SDK 提供了完整的社群管理能力，支持以下功能：

  • 创建/解散社群
  • 加入/离开社群
  • 查询已加入的社群列表及社群信息
  • 更新社群名称、头像、公告
  • 设置/删除社群自定义属性
  • 设置社群消息通知状态
  • 监听社群列表变更与信息更新

集成路线图

接入社群功能的推荐顺序如下：

  1. 创建/加入社群 — 社群管理
  2. 管理社群成员 — 社群成员管理
  3. 创建/管理频道 — 频道管理
  4. 收发频道消息 — 频道消息管理
  5. 管理频道会话 — 频道会话管理

前提条件

  • 请参考 实现基本消息收发 完成 ZIM SDK 获取、初始化和用户登录。
  • 请参考 使用 Token 鉴权 实现用户鉴权登录。
  • 社群功能需要 ZIM SDK 3.0.0 及以上版本。
  • 社群功能为旗舰版功能，使用前请联系 ZEGO 技术支持开通。
  • 社群功能的 Token 生成方式与其他 ZIM 功能一致，无需额外权限声明。
说明

社群管理操作目前仅支持通过客户端 SDK 调用，暂不支持服务端 API。社群事件通知目前仅通过客户端 SDK 回调接收，暂不支持服务端回调。

创建社群

登录 ZIM SDK 后，调用 createCommunity 接口，传入社群基础信息 ZIMCommunityInfo 与创建配置 ZIMCommunityCreateConfig 即可创建社群。创建者自动成为社群所有者。

创建结果通过 ZIMCommunityCreatedCallback 返回，成功后可获取社群的完整信息。

注意
  • communityID 支持开发者自定义，仅支持数字、英文字符及以下特殊字符：! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~，但不能以 # 开头。若不填，ZIM 服务端会创建以 #B 开头的 communityID 的社群。
  • 创建成功后即已加入社群，无需再调用加入接口。单用户最多加入社群数为 100（默认），可扩展至 500。同一 AppID 下社群数量无上限，同一社群下频道数量上限为 100（默认），可扩展至 1000。
import im.zego.zim.ZIM;
import im.zego.zim.callback.ZIMCommunityCreatedCallback;
import im.zego.zim.entity.ZIMCommunityCreateConfig;
import im.zego.zim.entity.ZIMCommunityFullInfo;
import im.zego.zim.entity.ZIMCommunityInfo;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.enums.ZIMErrorCode;

ZIMCommunityInfo communityInfo = new ZIMCommunityInfo();
communityInfo.setCommunityID("community_001"); // 可自定义，留空则由服务器自动生成以 #B 开头的 communityID
communityInfo.setCommunityName("我的社群"); // 最大长度300字符，可配置
communityInfo.setCommunityAvatarUrl("https://example.com/avatar.png"); // 最大长度100字符，可配置

ZIMCommunityCreateConfig config = new ZIMCommunityCreateConfig();
config.setCommunityNotice("欢迎加入！"); // 最大长度500字符，可配置
HashMap<String, String> attributes = new HashMap<>(); // 社群属性默认最多 10 对，key 最大长度 16 字符，value 最大长度 1024 字符
attributes.put("key1", "value1");
config.setCommunityAttributes(attributes);

zim.createCommunity(communityInfo, config, new ZIMCommunityCreatedCallback() {
    @Override
    public void onCommunityCreated(ZIMCommunityFullInfo communityFullInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 创建成功，communityFullInfo 包含社群完整信息
        }
    }
});
错误码说明处理建议
6001003社群已存在检查是否已创建过相同 communityID 的社群
6001007社群权限错误确认当前用户是否具有创建权限
6001008社群属性数量超限社群属性默认最多 10 对

ZIMCommunityInfo 字段说明

字段类型说明
communityIDString社群 ID，可自定义或由服务端自动生成
communityNameString社群名称，最大长度 300 字符，可配置
communityAvatarUrlString社群头像 URL，最大长度 100 字符，可配置

ZIMCommunityCreateConfig 参数说明

参数类型说明
communityNoticeString社群公告，最大长度 500 字符，可配置
communityAttributesMap<String, String>社群自定义属性，默认最多 10 对，key 最大长度 16 字符，value 最大长度 1024 字符

ZIMCommunityFullInfo 核心字段

字段类型说明
baseInfoZIMCommunityInfo社群基础信息（ID、名称、头像等）
communityNoticeString社群公告
communityAttributesHashMap<String, String>社群自定义属性
createTimelong社群创建时间
creatorUserIDString创建者用户 ID
currentMemberCountint当前社群成员数量
notificationStatusZIMCommunityMessageNotificationStatus消息通知状态

解散社群

社群所有者可调用 dismissCommunity 接口解散社群，解散后所有成员将无法再访问该社群。

注意
  • 只有社群所有者才能调用此接口，管理员和普通成员无权解散社群。
  • 社群解散后，其下所有频道也会自动解散。
zim.dismissCommunity(communityID, new ZIMCommunityDismissedCallback() {
    @Override
    public void onCommunityDismissed(String communityID, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 解散成功
        }
    }
});

加入社群

登录 ZIM SDK 后，调用 joinCommunity 接口，传入目标社群 ID 即可加入社群，加入成功后可获取该社群的完整信息。 加入社群后，会自动加入其下的默认频道和所有公共频道。 单用户最多加入社群数为 100（默认），可扩展至 500。

zim.joinCommunity(communityID, new ZIMCommunityJoinedCallback() {
    @Override
    public void onCommunityJoined(ZIMCommunityFullInfo communityFullInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 加入成功，communityFullInfo 包含社群完整信息
        }
    }
});

离开社群

已加入社群的成员可调用 leaveCommunity 接口主动离开社群。

注意
  • 社群所有者无法调用此接口离开社群，需先将所有权转让给其他成员或直接解散社群。
  • 离开社群同时也会离开其下所有的频道。
zim.leaveCommunity(communityID, new ZIMCommunityLeftCallback() {
    @Override
    public void onCommunityLeft(String communityID, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 离开成功
        }
    }
});

查询社群列表

调用 queryCommunityList 接口，分页拉取当前用户已加入的社群列表。

分页规则：

  • 首次查询时，将 config.nextFlag 设为 0。
  • 收到回调后，若返回的 nextFlag 不为 0，将其作为下一次请求的 config.nextFlag 继续拉取。
  • 当返回的 nextFlag 为 0 时，表示已无更多数据。
  • 每页查询的 count 最多 100。
ZIMCommunityListQueryConfig config = new ZIMCommunityListQueryConfig();
config.setNextFlag(0);  // 首次查询设为 0

zim.queryCommunityList(100, config, new ZIMCommunityListQueriedCallback() {
    @Override
    public void onCommunityListQueried(ArrayList<ZIMCommunity> communityList, long nextFlag, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // communityList 为当前页的社群列表
            // nextFlag != 0 时，可继续分页拉取
        }
    }
});

查询社群信息

调用 queryCommunityInfo 接口，查询指定社群的完整信息，包括社群名称、头像、公告、所有者等。

zim.queryCommunityInfo(communityID, new ZIMCommunityInfoQueriedCallback() {
    @Override
    public void onCommunityInfoQueried(ZIMCommunityFullInfo communityFullInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // communityFullInfo 包含社群完整信息
        }
    }
});

更新社群资料

社群所有者和管理员可以更新社群的基础资料，包括名称、头像和公告。

更新社群名称

调用 updateCommunityName 接口更新社群名称。社群名称最大长度 300 字符，可配置。

zim.updateCommunityName("新的社群名称", communityID, new ZIMCommunityNameUpdatedCallback() {
    @Override
    public void onCommunityNameUpdated(String communityID, String communityName, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 更新成功
        }
    }
});

更新社群头像

调用 updateCommunityAvatarUrl 接口更新社群头像。社群头像最大长度 100 字符，可配置。

zim.updateCommunityAvatarUrl("https://example.com/new_avatar.png", communityID,
    new ZIMCommunityAvatarUrlUpdatedCallback() {
        @Override
        public void onCommunityAvatarUrlUpdated(String communityID, String communityAvatarUrl, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

更新社群公告

调用 updateCommunityNotice 接口更新社群公告内容。社群公告最大长度 500 字符，可配置。

zim.updateCommunityNotice("新的社群公告内容", communityID, new ZIMCommunityNoticeUpdatedCallback() {
    @Override
    public void onCommunityNoticeUpdated(String communityID, String communityNotice, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 更新成功
        }
    }
});

设置社群属性

社群属性以键值对形式存储，可用于扩展社群的自定义信息，如分类标签、业务字段等。社群属性默认最多 10 对，key 最大长度 16 字符，value 最大长度 1024 字符。

设置属性

调用 setCommunityAttributes 接口，批量设置社群自定义属性。操作失败的键名将通过 errorKeys 列表返回。

HashMap<String, String> attributes = new HashMap<>();
attributes.put("key1", "value1");
attributes.put("key2", "value2");

zim.setCommunityAttributes(attributes, communityID, new ZIMCommunityAttributesOperatedCallback() {
    @Override
    public void onCommunityAttributesOperated(String communityID, ArrayList<String> errorKeys, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 设置成功，errorKeys 中列出操作失败的键
        }
    }
});

删除属性

调用 deleteCommunityAttributes 接口，按键名批量删除社群属性。

ArrayList<String> keys = new ArrayList<>();
keys.add("key1");
keys.add("key2");

zim.deleteCommunityAttributes(keys, communityID, new ZIMCommunityAttributesOperatedCallback() {
    @Override
    public void onCommunityAttributesOperated(String communityID, ArrayList<String> errorKeys, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 删除成功
        }
    }
});

设置社群通知状态

调用 setCommunityNotificationStatus 接口，设置当前用户在指定社群的消息通知状态。设置为免打扰后，该社群的新消息不会触发系统推送，未读消息数也不会累加到总未读数中。 用户进入社群后，社群默认是通知状态。但所有频道默认为免打扰状态。 社群总未读仅在社群为通知状态时会被计算，其值为所有通知状态的频道的未读数的总和。

zim.setCommunityNotificationStatus(
    ZIMCommunityMessageNotificationStatus.DO_NOT_DISTURB,
    communityID,
    new ZIMCommunityNotificationStatusSetCallback() {
        @Override
        public void onCommunityNotificationStatusSet(String communityID, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 设置成功
            }
        }
    });

监听社群变更

社群列表变更

当用户加入或离开社群、社群名称、头像、未读数更新等情况导致用户社群列表 UI 可能发生变化时，SDK 会触发 onCommunityListChanged 回调。回调中的 changeInfoList 包含变更类型（新增、删除、更新）及对应的社群信息。

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityListChanged(ZIM zim, ZIMCommunityListChangedEventResult result) {
        for (ZIMCommunityChangeInfo changeInfo : result.getChangeInfoList()) {
            // changeInfo.action：变更类型（新增/删除/更新）
            // changeInfo.community：变更的社群信息
        }
    }
});

社群信息更新

当社群资料（名称、头像、公告、属性等）发生变化时，SDK 会触发 onCommunityInfoUpdated 回调。updateInfoList 包含变更后的社群完整信息。

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityInfoUpdated(ZIM zim, ZIMCommunityInfoUpdatedEventResult result) {
        for (ZIMCommunityFullInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
            // updateInfo.communityInfo：更新后的社群完整信息
        }
    }
});

常见问题

Q: 社群功能需要什么 SDK 版本？ A: 社群功能需要 ZIM SDK 3.0.0 及以上版本。

Q: 社群管理是否支持服务端 API？ A: 社群管理操作目前仅支持通过客户端 SDK 调用，暂不支持服务端 API。

Q: 社群所有者能否离开社群？ A: 社群所有者无法直接离开社群，需先将所有权转让给其他成员或解散社群。

相关参考

上一篇

功能概述

下一篇

社群成员管理

当前页

返回到顶部