飞书群组管理

接口名称

飞书群组管理接口（租户令牌） - (IFeishuTenantV1ChatGroup)

功能描述

飞书群组 OpenAPI 提供了群组管理能力，包括创建群、解散群、更新群信息、获取群信息、管理群置顶以及获取群分享链接等。当前接口使用租户令牌访问，适应于租户应用场景。

参考文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateChatGroupAsync	创建群聊，创建时支持设置群头像、群名称、群主以及群类型等配置，同时支持邀请群成员、群机器人入群	租户令牌	POST
UpdateChatGroupByIdAsync	更新指定群的信息，包括群头像、群名称、群描述、群配置以及群主等	租户令牌	PUT
DeleteChatGroupAsync	通过 chat_id 解散指定群组。通过 API 解散群组后，群聊天记录将不会保存	租户令牌	DELETE
UpdateChatModerationAsync	更新指定群组的发言权限，可设置为所有群成员可发言、仅群主或管理员可发言、指定群成员可发言	租户令牌	PUT
GetChatGroupInoByIdAsync	获取指定群的基本信息，包括群名称、群描述、群头像、群主 ID 以及群权限配置等	租户令牌	GET
PutChatGroupTopNoticeAsync	更新群组中的群置顶信息，可以将群中的某一条消息，或群公告置顶展示	租户令牌	POST
DeleteChatGroupTopNoticeAsync	撤销指定群组中的置顶消息或群公告	租户令牌	POST
GetChatGroupPageListAsync	分页获取当前 access_token 所代表的用户或者机器人所在的群列表	租户令牌	GET
GetChatGroupPageListByKeywordAsync	分页获取当前身份（用户或机器人）可见的群列表，包括当前身份所在的群、对当前身份公开的群。支持关键词搜索、分页搜索	租户令牌	GET
GetChatGroupModeratorPageListByIdAsync	分页获取指定群组的发言模式、可发言用户名单等信息	租户令牌	GET
GetChatGroupShareLinkByIdAsync	获取指定群的分享链接，他人点击分享链接后可加入群组	租户令牌	GET

函数详细内容

创建群聊

函数签名：

csharp

Task<FeishuApiResult<CreateUpdateChatResult>?> CreateChatGroupAsync(
   [Body] CreateChatRequest createChatRequest,
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   [Query("set_bot_manager")] bool? set_bot_manager = false,
   [Query("uuid")] string? uuid = null,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
createChatRequest	CreateChatRequest	✅	创建群聊请求体	包含群名称、群头像、群类型等信息
user_id_type	string	⚪	用户 ID 类型	"open_id"
set_bot_manager	bool?	⚪	是否设置创建群的机器人为管理员	false
uuid	string?	⚪	请求去重的唯一标识符	"unique-request-id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "chat_id": "oc_a0553eda9014c201e6969b478895c230",
    "name": "新群聊",
    "avatar": "avatar_url",
    "description": "群描述"
  }
}

错误码：

33400: 请求参数错误
33403: 无权限创建群聊
33429: 频率限制

说明：

如果在请求体的 owner_id 字段指定了某个用户为群主，可以选择是否同时设置创建此群的机器人为管理员
持有相同 uuid + owner_id（若有）的请求 10 小时内只可成功创建 1 个群聊

代码示例：

typescript

// 创建群聊示例
const createChatRequest = {
  name: "项目讨论群",
  description: "用于项目相关讨论的群组",
  user_ids: ["user_001", "user_002"],
  bot_ids: ["bot_001"]
};

const response = await feishuClient.createChatGroupAsync(createChatRequest, "open_id", false, "unique-uuid-123");
if (response.code === 0) {
  console.log("群聊创建成功，群ID:", response.data.chat_id);
}

更新群信息

函数签名：

csharp

Task<FeishuApiResult<CreateUpdateChatResult>?> UpdateChatGroupByIdAsync(
    [Path] string chat_id,
    [Body] UpdateChatRequest updateChatRequest,
    [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
updateChatRequest	UpdateChatRequest	✅	更新群聊请求体	包含更新的群信息
user_id_type	string	⚪	用户 ID 类型	"open_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "chat_id": "oc_a0553eda9014c201e6969b478895c230",
    "name": "更新后的群名称",
    "description": "更新后的群描述"
  }
}

错误码：

33401: 群不存在
33403: 无权限修改群信息
33400: 请求参数错误

代码示例：

typescript

const updateRequest = {
  name: "新的群名称",
  description: "更新后的群描述",
  avatar: "new_avatar_url"
};

const response = await feishuClient.updateChatGroupByIdAsync(
  "oc_a0553eda9014c201e6969b478895c230", 
  updateRequest
);

解散群组

函数签名：

csharp

Task<FeishuNullDataApiResult?> DeleteChatGroupAsync(
   [Path] string chat_id,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"

响应：

json

{
  "code": 0,
  "msg": "success"
}

错误码：

33401: 群不存在
33403: 无权限解散群
33413: 群成员数超过限制，无法解散

说明：

通过 API 解散群组后，群聊天记录将不会保存
只有群主或管理员可以解散群组

代码示例：

typescript

const response = await feishuClient.deleteChatGroupAsync("oc_a0553eda9014c201e6969b478895c230");
if (response.code === 0) {
  console.log("群组解散成功");
}

更新群发言权限

函数签名：

csharp

Task<FeishuNullDataApiResult?> UpdateChatModerationAsync(
    [Path] string chat_id,
    [Body] UpdateChatModerationRequest updateChatModerationRequest,
    [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
updateChatModerationRequest	UpdateChatModerationRequest	✅	更新群发言权限请求体	包含发言权限配置
user_id_type	string	⚪	用户 ID 类型	"open_id"

响应：

json

{
  "code": 0,
  "msg": "success"
}

错误码：

33401: 群不存在
33403: 无权限修改群设置

代码示例：

typescript

const moderationRequest = {
  speak_permission: "all_members", // all_members, admin_only, some_members
  user_ids: ["user_001", "user_002"] // 当 speak_permission 为 some_members 时必填
};

const response = await feishuClient.updateChatModerationAsync(
  "oc_a0553eda9014c201e6969b478895c230",
  moderationRequest
);

获取群信息

函数签名：

csharp

Task<FeishuApiResult<GetChatGroupInfoResult>?> GetChatGroupInoByIdAsync(
   [Path] string chat_id,
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
user_id_type	string	⚪	用户 ID 类型	"open_id"

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "chat_id": "oc_a0553eda9014c201e6969b478895c230",
    "name": "群聊名称",
    "description": "群描述",
    "avatar": "avatar_url",
    "owner_id": "user_001",
    "chat_mode": "group",
    "chat_type": "private",
    "external": false,
    "tenant_key": "tenant_001"
  }
}

错误码：

33401: 群不存在
33403: 无权限查看群信息

代码示例：

typescript

const response = await feishuClient.getChatGroupInoByIdAsync("oc_a0553eda9014c201e6969b478895c230");
if (response.code === 0) {
  const groupInfo = response.data;
  console.log(`群名称: ${groupInfo.name}, 群主: ${groupInfo.owner_id}`);
}

设置群置顶消息

函数签名：

csharp

Task<FeishuNullDataApiResult?> PutChatGroupTopNoticeAsync(
  [Path] string chat_id,
  [Body] ChatTopNoticeRequest chatTopNoticeRequest,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
chatTopNoticeRequest	ChatTopNoticeRequest	✅	群置顶操作请求体	包含置顶消息或公告信息

响应：

json

{
  "code": 0,
  "msg": "success"
}

错误码：

33401: 群不存在
33403: 无权限设置置顶消息
33400: 请求参数错误

代码示例：

typescript

const topNoticeRequest = {
  message_type: "message", // message 或 announcement
  message_id: "msg_001" // 当 message_type 为 message 时必填
};

const response = await feishuClient.putChatGroupTopNoticeAsync(
  "oc_a0553eda9014c201e6969b478895c230",
  topNoticeRequest
);

取消群置顶消息

函数签名：

csharp

Task<FeishuNullDataApiResult?> DeleteChatGroupTopNoticeAsync(
  [Path] string chat_id,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"

响应：

json

{
  "code": 0,
  "msg": "success"
}

错误码：

33401: 群不存在
33403: 无权限取消置顶消息

代码示例：

typescript

const response = await feishuClient.deleteChatGroupTopNoticeAsync("oc_a0553eda9014c201e6969b478895c230");
if (response.code === 0) {
  console.log("置顶消息取消成功");
}

获取群列表

函数签名：

csharp

Task<FeishuApiPageListResult<ChatItemInfo>?> GetChatGroupPageListAsync(
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   [Query("sort_type")] string sort_type = "ByCreateTimeAsc",
   [Query("page_size")] int? page_size = 10,
   [Query("page_token")] string? page_token = null,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
user_id_type	string	⚪	用户 ID 类型	"open_id"
sort_type	string	⚪	群组排序方式	"ByCreateTimeAsc"
page_size	int?	⚪	分页大小	10
page_token	string?	⚪	分页标记	null

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "chat_id": "oc_a0553eda9014c201e6969b478895c230",
        "name": "群聊名称",
        "avatar": "avatar_url",
        "description": "群描述",
        "owner_id": "user_001"
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

错误码：

33403: 无权限获取群列表

说明：

ByCreateTimeAsc：按群组创建时间升序排列
ByActiveTimeDesc：按群组活跃时间降序排列（可能造成群组遗漏）

代码示例：

typescript

let pageToken = null;
let hasMore = true;

while (hasMore) {
  const response = await feishuClient.getChatGroupPageListAsync(
    "open_id",
    "ByCreateTimeAsc",
    20,
    pageToken
  );
  
  if (response.code === 0) {
    const groups = response.data.items;
    console.log(`获取到 ${groups.length} 个群组`);
    
    hasMore = response.data.has_more;
    pageToken = response.data.page_token;
  }
}

关键词搜索群列表

函数签名：

csharp

Task<FeishuApiPageListResult<ChatItemInfo>?> GetChatGroupPageListByKeywordAsync(
   [Query("query")] string? query = "",
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   [Query("sort_type")] string sort_type = "ByCreateTimeAsc",
   [Query("page_size")] int? page_size = 10,
   [Query("page_token")] string? page_token = null,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
query	string?	⚪	搜索关键词	"项目讨论"
user_id_type	string	⚪	用户 ID 类型	"open_id"
sort_type	string	⚪	群组排序方式	"ByCreateTimeAsc"
page_size	int?	⚪	分页大小	10
page_token	string?	⚪	分页标记	null

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "chat_id": "oc_a0553eda9014c201e6969b478895c230",
        "name": "项目讨论群",
        "avatar": "avatar_url"
      }
    ],
    "page_token": "next_page_token",
    "has_more": false
  }
}

错误码：

33403: 无权限搜索群组

代码示例：

typescript

const response = await feishuClient.getChatGroupPageListByKeywordAsync(
  "项目讨论",
  "open_id",
  "ByCreateTimeAsc",
  10
);

if (response.code === 0) {
  const groups = response.data.items;
  console.log(`搜索到 ${groups.length} 个匹配的群组`);
}

获取群发言权限列表

函数签名：

csharp

Task<FeishuApiResult<ChatGroupModeratorPageListResult>?> GetChatGroupModeratorPageListByIdAsync(
  [Path] string chat_id,
  [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
  [Query("page_size")] int? page_size = 10,
  [Query("page_token")] string? page_token = null,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
user_id_type	string	⚪	用户 ID 类型	"open_id"
page_size	int?	⚪	分页大小	10
page_token	string?	⚪	分页标记	null

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "speak_permission": "some_members",
    "user_ids": ["user_001", "user_002"],
    "page_token": "next_page_token",
    "has_more": false
  }
}

错误码：

33401: 群不存在
33403: 无权限查看群权限设置

代码示例：

typescript

const response = await feishuClient.getChatGroupModeratorPageListByIdAsync(
  "oc_a0553eda9014c201e6969b478895c230",
  "open_id",
  50
);

if (response.code === 0) {
  const moderation = response.data;
  console.log(`发言权限: ${moderation.speak_permission}`);
  console.log(`可发言用户数: ${moderation.user_ids.length}`);
}

获取群分享链接

函数签名：

csharp

Task<FeishuApiResult<ShareLinkDataResult>?> GetChatGroupShareLinkByIdAsync(
 [Path] string chat_id,
 [Body] ShareLinkRequest shareLinkRequest,
 CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	含义	示例值
chat_id	string	✅	群 ID	"oc_a0553eda9014c201e6969b478895c230"
shareLinkRequest	ShareLinkRequest	✅	获取群分享链接请求体	包含分享链接配置

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "share_link": "https://example.com/join/group/abc123",
    "expire_time": 1640995200
  }
}

说明：

他人点击分享链接后可加入群组
分享链接可能设置过期时间

代码示例：

typescript

const shareLinkRequest = {
  expire_seconds: 86400 // 24小时后过期
};

const response = await feishuClient.getChatGroupShareLinkByIdAsync(
  "oc_a0553eda9014c201e6969b478895c230",
  shareLinkRequest
);

if (response.code === 0) {
  console.log(`分享链接: ${response.data.share_link}`);
  console.log(`过期时间: ${response.data.expire_time}`);
}

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

消息管理

群组管理

群组公告管理

群组成员管理

会话标签页管理

飞书群组管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建群聊

更新群信息

解散群组

更新群发言权限

获取群信息

设置群置顶消息

取消群置顶消息

获取群列表

关键词搜索群列表

获取群发言权限列表

获取群分享链接

飞书群组管理 ​

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

创建群聊 ​

更新群信息 ​

解散群组 ​

更新群发言权限 ​

获取群信息 ​

设置群置顶消息 ​

取消群置顶消息 ​

获取群列表 ​

关键词搜索群列表 ​

获取群发言权限列表 ​

获取群分享链接 ​

飞书群组管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建群聊

更新群信息

解散群组

更新群发言权限

获取群信息

设置群置顶消息

取消群置顶消息

获取群列表

关键词搜索群列表

获取群发言权限列表

获取群分享链接