# 群组概述 企业或团队内 “拉群” 是一种常用的沟通方式，通过群聊推进多人之间的交流协作。开放平台为飞书群组提供了 OpenAPI，用于管理群组、群成员、群公告以及群菜单等。 ## 典型场景 开放平台提供了包含消息与群组业务的集成方案，详情可参见： - [从通知到高效协同，飞书统一告警方案让服务保障坚如磐石](https://open.larkoffice.com/solutions/detail/alert) - [当项目管理遇见飞书，协同沉淀更便捷](https://open.larkoffice.com/solutions/detail/project) ## 接入流程 群组 API 的基本接入流程如下图所示，如需了解详细的 API 接入流程，参见[流程概述](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7e2c712313cbc2da9b298804cbcf94e2_yZOtP0cS3V.png?height=214&lazyload=true&maxWidth=700&width=2276) **说明**： - 你的应用必须[启用机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)才可以调用群组 API。如需了解应用机器人，可参见[应用机器人概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/bot-v3/bot-overview#75133a93#75133a93)。 - 应用机器人支持添加到外部群或与外部用户单聊，具体配置操作参考[机器人支持外部群和外部用户单聊](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/develop-robots/add-bot-to-external-group)。 ## 开发教程 体验场景化教程，了解如何运用消息与群组 API 助力企业高效通讯。 - 场景一：[机器人自动拉群报警](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-development-tutorial/introduction) ![14机器人自动拉群报警.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/69e9999ad015bca8e79c50f1229fbc61_pBAn6j9TCi.png?height=400&lazyload=true&maxWidth=600&width=752) - 场景二：[新人入群欢迎机器人](https://open.feishu.cn/document/home/event-based-messaging/introduction) ![13将企业组织架构同步到飞书cn.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8c385d02b353ac4d5569a37b81156f77_7cEJornbRS.png?height=400&lazyload=true&maxWidth=600&width=752) ## 资源介绍 群组业务域以资源为中心进行开放。资源的关系图如下，通过 OpenAPI 管理群成员、公告、标签页以及菜单等资源。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d4e2853106bc6e6087f279984e813380_S7Kyy7dSwE.png?height=1214&lazyload=true&maxWidth=600&width=1288) 各资源介绍如下： 资源 | 介绍 ---|--- [群组管理](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/chat/chat-info/intro) | 包括创建群、解散群、更新群信息、获取群信息、设置群权限等管理操作。 [群成员](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/chat/chat-member/intro) | 包括指定群管理员、邀请用户或机器人进群、获取群成员等操作。 [群公告](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/chat/chat-announcement/intro) | 更新或获取群公告。 [会话标签页](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/create) | 群聊顶部可自定义多个标签页，用于收集文档、Pin 消息、会议纪要等信息。 [群菜单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_tree/overview) | 群聊内可添加群菜单，成员可通过菜单选项实现一键跳转功能。 ## 方法列表 以下提供群组业务域所包含的所有 API 与事件列表 文中表格涉及的 **商店** 是指商店应用，**自建** 是指企业自建应用。应用类型说明参见[应用类型简介](https://open.feishu.cn/document/home/app-types-introduction/overview)。 ### 群组管理 #### API 列表 **[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [创建群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/create)
`POST` /open-apis/im/v1/chats
> 创建群并设置群头像、群名、群描述等。 | 获取与更新群组信息(im:chat)
创建群(im:chat:create) | `tenant_access_token` | **✓** | **✓** [获取群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)
`GET` /open-apis/im/v1/chats/:chat_id
> 获取群名称、群描述、群头像、群主 ID 等群基本信息。 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取用户或机器人所在的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/list)
`GET` /open-apis/im/v1/chats
>用户获取用户或者机器人所在的群列表。 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly)
读取群信息（历史版本）(im:chat.group_info:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [搜索对用户或机器人可见的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/search)
`GET` /open-apis/im/v1/chats/search
>用于搜索对用户、机器人可见的群列表 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly)
读取群信息（历史版本）(im:chat.group_info:readonly) | `tenant_access_token`
`user
_access_token` | **✓** | **✓** [获取群成员发言权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-moderation/get)
`GET` /open-apis/im/v1/chats/:chat_id/moderation
> 获取群发言模式、可发言用户名单等。 | 获取与更新群组信息(im:chat)
查看群发言权限(im:chat.moderation:read)
获取群组信息(im:chat:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取群分享链接](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/link)
`POST` /open-apis/im/v1/chats/:chat_id/link
> 获取指定群的分享链接。 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [更新群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/update)
`PUT` /open-apis/im/v1/chats/:chat_id
> 更新群头像、群名称、群描述、群配置、转让群主等。 | 获取与更新群组信息(im:chat)
更新群信息(im:chat:update) | `tenant_access_token` | **✓** | **✓** [更新群发言权限](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-moderation/update)
`PUT` /open-apis/im/v1/chats/:chat_id/moderation
> 更新群组的发言权限设置，可设置为全员可发言、仅管理员可发言或指定用户可发言。 | 获取与更新群组信息(im:chat)
操作群发言权限(im:chat:moderation:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [更新群置顶](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-top_notice/put_top_notice)
`POST` /open-apis/im/v1/chats/:chat_id/top_notice/put_top_notice
> 更新会话中的群置顶信息，可以将群中的某一条消息，或者群公告置顶显示。 | 获取与更新群组信息(im:chat)
操作群置顶(im:chat.top_notice:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [撤销群置顶](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-top_notice/delete_top_notice)
`POST` /open-apis/im/v1/chats/:chat_id/top_notice/delete_top_notice
> 撤销会话中的置顶。 | 获取与更新群组信息(im:chat)
操作群置顶(im:chat.top_notice:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [解散群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/delete)
`DELETE` /open-apis/im/v1/chats/:chat_id
>解散群聊。 | 获取与更新群组信息(im:chat)
解散群(im:chat:delete) | `tenant_access_token`
`user_access_token` | **✓** | **✓** #### 事件列表 **[事件 (Event)](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|--- [群解散](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/events/disbanded)
> 群组被解散后触发此事件。 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly) | im.chat.disbanded_v1 | **✓** | **✓** [群配置修改](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/events/updated)
> 群组配置被修改后触发此事件，包含：群主转移、群基本信息修改、群权限修改 | 获取与更新群组信息(im:chat)
查看群信息(im:chat:read)
获取群组信息(im:chat:readonly) | im.chat.updated_v1 | **✓** | **✓** ### 群成员 #### API 列表 **[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [指定群管理员](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-managers/add_managers)
`POST` /open-apis/im/v1/chats/:chat_id/managers/add_managers
> 将用户或机器人指定为群管理员。 | 获取与更新群组信息(im:chat)
添加、删除群管理员(im:chat.managers:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [删除群管理员](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-managers/delete_managers)
`POST` /open-apis/im/v1/chats/:chat_id/managers/delete_managers
> 删除指定的群管理员（用户或机器人）。 | 获取与更新群组信息(im:chat)
添加、删除群管理员(im:chat.managers:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [将用户或机器人拉入群聊](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/create)
`POST` open-apis/im/v1/chats/:chat_id/members
> 将用户或机器人拉入群聊。 | 获取与更新群组信息(im:chat)
添加、移除群成员(im:chat.members:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [将用户或机器人移出群聊](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/delete)
`DELETE` /open-apis/im/v1/chats/:chat_id/members
> 将用户或机器人移出群聊。 | 获取与更新群组信息(im:chat)
添加、移除群成员(im:chat.members:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [用户或机器人主动加入群聊](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/me_join)
`PATCH` /open-apis/im/v1/chats/:chat_id/members/me_join
> 用户或者机器人可以通过接口入群。 | 获取与更新群组信息(im:chat)
添加、移除群成员(im:chat.members:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取群成员列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/get)
`GET` /open-apis/im/v1/chats/:chat_id/members
>获取群里成员列表。 | 获取与更新群组信息(im:chat)
查看群成员(im:chat.members:read)
获取群组信息(im:chat:readonly)
读取群信息（历史版本）(im:chat.group_info:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [判断用户或机器人是否在群里](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/is_in_chat)
`GET` /open-apis/im/v1/chats/:chat_id/members/is_in_chat
>判断用户或机器人是否在群里。 | 获取与更新群组信息(im:chat)
查看群成员(im:chat.members:read)
获取群组信息(im:chat:readonly)
读取群信息（历史版本）(im:chat.group_info:readonly) | `tenant_access_token`
`usert_access_token` | **✓** | **✓** #### 事件列表 **[事件 (Event)](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 权限要求（满足任一） | 事件类型 | 商店 | 自建 ---|---|---|---|--- [机器人进群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-member-bot/events/added)
> 机器人被添加至群聊时触发此事件。 | 获取与更新群组信息(im:chat)
订阅机器人进、出群事件(im:chat.members:bot_access)
获取群组信息(im:chat:readonly) | im.chat.member.bot.added_v1 | **✓** | **✓** [机器人被移出群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-member-bot/events/deleted)
> 机器人被移出群聊后触发此事件。 | 获取与更新群组信息(im:chat)
订阅机器人进、出群事件(im:chat.members:bot_access)
获取群组信息(im:chat:readonly) | im.chat.member.bot.deleted_v1 | **✓** | **✓** [用户进群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-member-user/events/added)
> 新用户进群触发此事件。 | 获取与更新群组信息(im:chat)
查看群成员(im:chat.members:read)
获取群组信息(im:chat:readonly) | im.chat.member.user.added_v1 | **✓** | **✓** [用户出群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-member-user/events/deleted)
> 用户主动退群或被移出群聊时推送事件。 | 获取与更新群组信息(im:chat)
查看群成员(im:chat.members:read)
获取群组信息(im:chat:readonly) | im.chat.member.user.deleted_v1 | **✓** | **✓** [撤销拉用户进群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/events/deleted)
> 撤销拉用户进群后触发此事件。 | 获取与更新群组信息(im:chat)
查看群成员(im:chat.members:read)
获取群组信息(im:chat:readonly) | im.chat.member.user.withdrawn_v1 | **✓** | **✓** [用户和机器人的会话首次被创建](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/bot-events)
> 当用户首次与机器人单聊时触发此事件。 | 无 | p2p_chat_create | **✓** | **✓** [用户进入与机器人的会话](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-access_event/events/bot_p2p_chat_entered)
> 用户进入与机器人的会话时触发此事件。 | 无 | im.chat.access_event.bot_p2p_chat_entered_v1 | **✓** | **✓** ### 群公告 #### API 列表 **[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [更新群公告信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-announcement/patch)
`PATCH` /open-apis/im/v1/chats/:chat_id/announcement
> 更新会话中的群公告信息，更新公告信息的格式和更新云文档格式相同。 | 获取与更新群组信息(im:chat)
更新群公告内容(im:chat.announcement:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [获取群公告信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-announcement/get)
`GET` /open-apis/im/v1/chats/:chat_id/announcement
> 获取会话中的群公告信息，公告信息格式与云文档格式相同。 | 获取与更新群组信息(im:chat)
查看群公告信息(im:chat.announcement:read)
获取群组信息(im:chat:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** ### 会话标签页 #### API 列表 **[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [添加会话标签页](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/create)
`POST` /open-apis/im/v1/chats/:chat_id/chat_tabs
> 添加自定义会话标签页。 | 获取与更新群组信息(im:chat)
操作群会话标签页(im:chat.tabs:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [更新会话标签页](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/update_tabs)
`POST` /open-apis/im/v1/chats/:chat_id/chat_tabs/update_tabs
> 更新会话标签页。 | 获取与更新群组信息(im:chat)
操作群会话标签页(im:chat.tabs:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [会话标签页排序](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/sort_tabs)
`POST` /open-apis/im/v1/chats/:chat_id/chat_tabs/sort_tabs
> 会话标签页排序。 | 获取与更新群组信息(im:chat)
操作群会话标签页(im:chat.tabs:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [拉取会话标签页](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/list_tabs)
`GET` /open-apis/im/v1/chats/:chat_id/chat_tabs/list_tabs
> 拉取会话标签页。 | 获取与更新群组信息(im:chat)
查看群会话标签页(im:chat.tabs:read)
获取群组信息(im:chat:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓** [删除会话标签页](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-tab/delete_tabs)
`DELETE` /open-apis/im/v1/chats/:chat_id/chat_tabs/delete_tabs
> 删除会话标签页。 | 获取与更新群组信息(im:chat)
操作群会话标签页(im:chat.tabs:write_only) | `tenant_access_token`
`user_access_token` | **✓** | **✓** ### 群菜单 #### API 列表 **[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建 ---|---|---|---|--- [添加群菜单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_tree/create)
`POST` /open-apis/im/v1/chats/:chat_id/menu_tree
> 该接口用于向群组中添加群菜单。 | 获取与更新群组信息(im:chat)
操作群菜单(im:chat.menu_tree:write_only) | `tenant_access_token` | **✓** | **✓** [修改群菜单元信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_item/patch)
`PATCH` /open-apis/im/v1/chats/:chat_id/menu_items/:menu_item_id
> 修改某个一级菜单或者二级菜单的元信息，包括群菜单的图标、名称、国际化名称和跳转链接。 | 获取与更新群组信息(im:chat)
操作群菜单(im:chat.menu_tree:write_only) | `tenant_access_token` | **✓** | **✓** [排序群菜单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_tree/sort)
`POST` /open-apis/im/v1/chats/:chat_id/menu_tree/sort
> 给一个群内的一级菜单排序。 | 获取与更新群组信息(im:chat)
操作群菜单(im:chat.menu_tree:write_only) | `tenant_access_token` | **✓** | **✓** [获取群菜单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_tree/get)
`GET` /open-apis/im/v1/chats/:chat_id/menu_tree
> 通过群 ID 获取群内菜单。 | 获取与更新群组信息(im:chat)
查看群菜单(im:chat.menu_tree:read)
获取群组信息(im:chat:readonly) | `tenant_access_token` | **✓** | **✓** [删除群菜单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-menu_tree/delete)
`DELETE` /open-apis/im/v1/chats/:chat_id/menu_tree
> 该接口用于删除群内已经添加的群菜单。 | 获取与更新群组信息(im:chat)
操作群菜单(im:chat.menu_tree:write_only) | `tenant_access_token` | **✓** | **✓**