社群管理

2026-05-22

功能简介

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

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

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

集成路线图

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

创建/加入社群 — 社群管理
管理社群成员 — 社群成员管理
创建/管理频道 — 频道管理
收发频道消息 — 频道消息管理
管理频道会话 — 频道会话管理

前提条件

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

说明

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

创建社群

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

注意

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

示例代码

const communityInfo: ZIMCommunityInfo = {
    communityID: 'community_001', // 可自定义，留空则由服务器自动生成以 #B 开头的 communityID 
    communityName: '我的社群', // 最大长度300字符，可配置
    communityAvatarUrl: 'https://example.com/avatar.png', // 最大长度100字符，可配置
};
const config: ZIMCommunityCreateConfig = {
    communityNotice: '欢迎加入！', // 最大长度500字符，可配置 
    communityAttributes: { key1: 'value1' }, // 社群属性默认最多 10 对，key 最大长度 16 字符，value 最大长度 1024 字符
};

zim.createCommunity(communityInfo, config)
    .then((result: ZIMCommunityCreatedResult) => {
        // 创建成功，result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 创建失败
    });

const communityInfo: ZIMCommunityInfo = {
    communityID: 'community_001', // 可自定义，留空则由服务器自动生成以 #B 开头的 communityID 
    communityName: '我的社群', // 最大长度300字符，可配置
    communityAvatarUrl: 'https://example.com/avatar.png', // 最大长度100字符，可配置
};
const config: ZIMCommunityCreateConfig = {
    communityNotice: '欢迎加入！', // 最大长度500字符，可配置 
    communityAttributes: { key1: 'value1' }, // 社群属性默认最多 10 对，key 最大长度 16 字符，value 最大长度 1024 字符
};

zim.createCommunity(communityInfo, config)
    .then((result: ZIMCommunityCreatedResult) => {
        // 创建成功，result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 创建失败
    });

常见错误码

错误码	说明	处理建议
6001003	社群已存在	检查是否已创建过相同 communityID 的社群
6001007	社群权限错误	确认当前用户是否具有创建权限
6001008	社群属性数量超限	社群属性默认最多 10 对

ZIMCommunityInfo 字段说明

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

ZIMCommunityCreateConfig 参数说明

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

ZIMCommunityFullInfo 核心字段

字段	类型	说明
baseInfo	ZIMCommunityInfo	社群基础信息（ID、名称、头像等）
communityNotice	String	社群公告
communityAttributes	HashMap<String, String>	社群自定义属性
createTime	long	社群创建时间
creatorUserID	String	创建者用户 ID
currentMemberCount	int	当前社群成员数量
notificationStatus	ZIMCommunityMessageNotificationStatus	消息通知状态

解散社群

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

注意

只有社群所有者才能调用此接口，管理员和普通成员无权解散社群。
社群解散后，其下所有频道也会自动解散。

示例代码

zim.dismissCommunity(communityID)
    .then((result: ZIMCommunityDismissedResult) => {
        // 解散成功
    })
    .catch((err: ZIMError) => {
        // 解散失败
    });

zim.dismissCommunity(communityID)
    .then((result: ZIMCommunityDismissedResult) => {
        // 解散成功
    })
    .catch((err: ZIMError) => {
        // 解散失败
    });

加入社群

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

示例代码

zim.joinCommunity(communityID)
    .then((result: ZIMCommunityJoinedResult) => {
        // 加入成功，result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 加入失败
    });

zim.joinCommunity(communityID)
    .then((result: ZIMCommunityJoinedResult) => {
        // 加入成功，result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 加入失败
    });

离开社群

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

注意

社群所有者无法调用此接口离开社群，需先将所有权转让给其他成员或直接解散社群。
离开社群同时也会离开其下所有的频道。

示例代码

zim.leaveCommunity(communityID)
    .then((result: ZIMCommunityLeftResult) => {
        // 离开成功
    })
    .catch((err: ZIMError) => {
        // 离开失败
    });

zim.leaveCommunity(communityID)
    .then((result: ZIMCommunityLeftResult) => {
        // 离开成功
    })
    .catch((err: ZIMError) => {
        // 离开失败
    });

查询社群列表

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

分页规则：

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

示例代码

const config: ZIMCommunityListQueryConfig = { nextFlag: 0 };

zim.queryCommunityList(100, config)
    .then((result: ZIMCommunityListQueriedResult) => {
        const { communityList, nextFlag } = result;
        // nextFlag != 0 时继续分页拉取
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

const config: ZIMCommunityListQueryConfig = { nextFlag: 0 };

zim.queryCommunityList(100, config)
    .then((result: ZIMCommunityListQueriedResult) => {
        const { communityList, nextFlag } = result;
        // nextFlag != 0 时继续分页拉取
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

查询社群信息

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

示例代码

zim.queryCommunityInfo(communityID)
    .then((result: ZIMCommunityInfoQueriedResult) => {
        // result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

zim.queryCommunityInfo(communityID)
    .then((result: ZIMCommunityInfoQueriedResult) => {
        // result.communityInfo 包含社群完整信息
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

更新社群资料

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

更新社群名称

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

示例代码

zim.updateCommunityName('新的社群名称', communityID)
    .then((result: ZIMCommunityNameUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

zim.updateCommunityName('新的社群名称', communityID)
    .then((result: ZIMCommunityNameUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

更新社群头像

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

示例代码

zim.updateCommunityAvatarUrl('https://example.com/new_avatar.png', communityID)
    .then((result: ZIMCommunityAvatarUrlUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

zim.updateCommunityAvatarUrl('https://example.com/new_avatar.png', communityID)
    .then((result: ZIMCommunityAvatarUrlUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

更新社群公告

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

示例代码

zim.updateCommunityNotice('新的社群公告内容', communityID)
    .then((result: ZIMCommunityNoticeUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

zim.updateCommunityNotice('新的社群公告内容', communityID)
    .then((result: ZIMCommunityNoticeUpdatedResult) => {
        // 更新成功
    })
    .catch((err: ZIMError) => {
        // 更新失败
    });

设置社群属性

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

设置属性

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

示例代码

const attributes: Record<string, string> = { key1: 'value1', key2: 'value2' };

zim.setCommunityAttributes(attributes, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // result.errorKeys 列出操作失败的键
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });

const attributes: Record<string, string> = { key1: 'value1', key2: 'value2' };

zim.setCommunityAttributes(attributes, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // result.errorKeys 列出操作失败的键
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });

删除属性

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

示例代码

const keys = ['key1', 'key2'];

zim.deleteCommunityAttributes(keys, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // 删除成功
    })
    .catch((err: ZIMError) => {
        // 删除失败
    });

const keys = ['key1', 'key2'];

zim.deleteCommunityAttributes(keys, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // 删除成功
    })
    .catch((err: ZIMError) => {
        // 删除失败
    });

设置社群通知状态

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

示例代码

// status: 1 = 接收通知，2 = 免打扰
zim.setCommunityNotificationStatus(2, communityID)
    .then((result: ZIMCommunityNotificationStatusSetResult) => {
        // 设置成功
    })
    .catch((err: ZIMError) => {
        // 设置失败
    });

// status: 1 = 接收通知，2 = 免打扰
zim.setCommunityNotificationStatus(2, communityID)
    .then((result: ZIMCommunityNotificationStatusSetResult) => {
        // 设置成功
    })
    .catch((err: ZIMError) => {
        // 设置失败
    });

监听社群变更

社群列表变更

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

示例代码

zim.on('communityListChanged', (zim, result) => {
    for (const changeInfo of result.changeInfoList) {
        // changeInfo.action：变更类型（新增/删除/更新）
        // changeInfo.community：变更的社群信息
    }
});

zim.on('communityListChanged', (zim, result) => {
    for (const changeInfo of result.changeInfoList) {
        // changeInfo.action：变更类型（新增/删除/更新）
        // changeInfo.community：变更的社群信息
    }
});

社群信息更新

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

示例代码

zim.on('communityInfoUpdated', (zim, result) => {
    for (const updateInfo of result.updateInfoList) {
        // updateInfo.communityInfo：更新后的社群完整信息
    }
});

zim.on('communityInfoUpdated', (zim, result) => {
    for (const updateInfo of result.updateInfoList) {
        // updateInfo.communityInfo：更新后的社群完整信息
    }
});

常见问题

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

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

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

社群管理

功能简介

集成路线图

前提条件

创建社群

ZIMCommunityInfo 字段说明

ZIMCommunityCreateConfig 参数说明

ZIMCommunityFullInfo 核心字段

解散社群

加入社群

离开社群

查询社群列表

查询社群信息

更新社群资料

更新社群名称

更新社群头像

更新社群公告

设置社群属性

设置属性

删除属性

设置社群通知状态

监听社群变更

社群列表变更

社群信息更新

常见问题

相关参考