飞书开放平台 Server API 文档

主题

更新群信息 ​

更新指定群的信息，包括群头像、群名称、群描述、群配置以及群主等。

前提条件 ​

应用需要开启机器人能力。

使用限制 ​

  • 对于群主和群管理员，或是创建群组且具备 ==更新应用所创建群的群信息（im:chat:operate_as_owner）== 权限的机器人，可调用本接口更新所有信息。

  • 对于不满足上述权限条件的群成员或机器人：

    • 如果群设置中配置了 所有群成员可编辑群信息，则仅可更新群头像、群名称、群描述、群国际化名称信息。
    • 如果群设置中配置了 仅群主和群管理员可编辑群信息，则无法修改任何群信息。

注意事项 ​

调用该接口时，未传值的请求参数默认不更新，保持原有群信息。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/im/v1/chats/:chat_id
HTTP MethodPUT
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可im:chat 获取与更新群组信息 im:chat:update 更新群信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
chat_idstring群 ID。获取方式：
- 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
注意：仅支持群模式为 group 的群组 ID。你可以调用获取群信息接口，在返回结果中查看 chat_mode 参数取值是否为 group。
示例值："oc_a0553eda9014c201e6969b478895c230"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
avatarstring否群头像对应的 Image Key，可通过上传图片获取（注意：上传图片的 ==image_type== 需要指定为 ==avatar==）
示例值："default-avatar_44ae0ca3-e140-494b-956f-78091e348435"
namestring否群名称
注意： - 建议群名称不超过 60 字符 - 公开群名称的长度不得少于 2 个字符
示例值："群聊"
descriptionstring否群描述，建议不超过 100 字符
示例值："测试群描述"
i18n_namesi18n_names否群国际化名称，建议不超过 60 字符
  └ zh_cnstring否中文名
示例值："群聊"
  └ en_usstring否英文名
示例值："group chat"
  └ ja_jpstring否日文名
示例值："グループチャット"
add_member_permissionstring否谁可以添加群成员，群成员包括用户或机器人
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
注意：add_member_permission 和 share_card_permission 两个参数必须同步配置。
- 如果 add_member_permission 值为 only_owner，则 share_card_permission 只能设置为 not_allowed。 - 如果 add_member_permission 值为all_members，则 share_card_permission 只能设置为 allowed。
示例值："all_members"
share_card_permissionstring否是否允许分享群
可选值有： - allowed：允许 - not_allowed：不允许
注意：add_member_permission 和 share_card_permission 两个参数必须同步配置。
- 如果 add_member_permission 值为 only_owner，则 share_card_permission 只能设置为 not_allowed。 - 如果 add_member_permission 值为all_members，则 share_card_permission 只能设置为 allowed。
示例值："allowed"
at_all_permissionstring否谁可以 at 所有人
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
示例值："all_members"
edit_permissionstring否谁可以编辑群信息
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
示例值："all_members"
owner_idstring否新群主的用户 ID，不转让群主时无需填写。ID 类型与查询参数 user_id_type 取值一致，ID 类型推荐使用 OpenID，获取方式可参考文档如何获取 Open ID？。
示例值："4d7a3c6g"
join_message_visibilitystring否成员入群提示消息的可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
示例值："only_owner"
leave_message_visibilitystring否成员退群提示消息的可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
示例值："only_owner"
membership_approvalstring否加群是否需要审批
可选值有： - no_approval_required：无需审批 - approval_required：需要审批
示例值："no_approval_required"
restricted_mode_settingrestricted_mode_setting否保密模式设置
注意：保密模式适用于企业旗舰版。适用版本与功能介绍参见会话保密模式。
  └ statusboolean否保密模式是否开启
可选值有：
- true：开启。设置为 ture 时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting 不能全为 all_members。 - false：不开启。设置为 false 时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting 不能存在 not_anyone。
示例值：false
  └ screenshot_has_permission_settingstring否允许截屏录屏
示例值："all_members"
可选值有：
- all_members: 所有成员允许截屏录屏 - not_anyone: 所有成员禁止截屏录屏
  └ download_has_permission_settingstring否允许下载消息中图片、视频和文件
示例值："all_members"
可选值有：
- all_members: 所有成员允许下载资源 - not_anyone: 所有成员禁止下载资源
  └ message_has_permission_settingstring否允许复制和转发消息
示例值："all_members"
可选值有：
- all_members: 所有成员允许复制和转发消息 - not_anyone: 所有成员禁止复制和转发消息
chat_typestring否群类型
可选值有： - private：私有群 - public：公开群
示例值："private"
group_message_typestring否群消息形式
示例值："chat"
可选值有：
- chat: 对话消息 - thread: 话题消息
urgent_settingstring否谁可以加急
示例值："all_members"
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
video_conference_settingstring否谁可以发起视频会议
示例值："all_members"
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
hide_member_count_settingstring否隐藏群成员人数设置
示例值："all_members"
可选值有：
- all_members: 所有群成员可见 - only_owner: 仅群主群管理员可见

请求体示例 ​

json
{
    "avatar": "default-avatar_44ae0ca3-e140-494b-956f-78091e348435",
    "name": "群聊",
    "description": "测试群描述",
    "i18n_names": {
        "zh_cn": "群聊",
        "en_us": "group chat",
        "ja_jp": "グループチャット"
    },
    "add_member_permission": "all_members",
    "share_card_permission": "allowed",
    "at_all_permission": "all_members",
    "edit_permission": "all_members",
    "owner_id": "4d7a3c6g",
    "join_message_visibility": "only_owner",
    "leave_message_visibility": "only_owner",
    "membership_approval": "no_approval_required",
    "restricted_mode_setting": {
        "status": false,
        "screenshot_has_permission_setting": "all_members",
        "download_has_permission_setting": "all_members",
        "message_has_permission_setting": "all_members"
    },
    "chat_type": "private",
    "group_message_type": "chat",
    "urgent_setting": "all_members",
    "video_conference_setting": "all_members",
    "hide_member_count_setting": "all_members"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--

响应体示例 ​

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

错误码 ​

HTTP状态码错误码描述排查建议
400232001Your request contains an invalid request parameter.参数错误。请参考 API 文档参数描述，排查请求时参数是否填写有误。
400232002No Permission: Only chat owner or admin can edit chat information in the current situation.当前只允许群组的群主或群管理员更新群信息。
400232004Such an app does NOT exist.作为操作者的 app_id 不存在，请联系技术支持。
400232006Your request specifies a chat_id which is invalid.无效的 chat_id，请检查 chat_id 是否正确。获取方式： - 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
400232008Your request specifies a chat whose type is NOT supported currently.不支持的群模式（chat_mode）或群类型（chat_type）。你可以调用获取群信息接口，查看群信息是否符合当前接口的要求。
400232009Your request specifies a chat which has already been dissolved.群组已被解散，无法操作。
400232010Operator and chat can NOT be in different tenants.调用接口的操作者和被操作的群组不在同一租户下，无法操作。需确保当前的操作者和被操作的群组在同一租户下。
400232011Operator can NOT be out of the chat.调用接口的操作者不在群组内，无法操作。你需要将当前调用 API 的应用或用户加入待操作的群组后重试。
400232012New chat owner can NOT be out of the chat.新群主（owner_id）不在群组中，无法操作。你需要邀请用户入群后重试。
400232016Non-chat-owner or Non-chat-admin can only edit certain parts.非群主或群管理员的普通群成员，只能修改部分群信息 ，包括：群头像（avatar）、群名称（name）、群描述（description）、群国际化名称（i18n_names)。
400232019The request has been rate limited.触发群限流，请控制请求的速度，详情参见频控策略。
400232023Chat information review failed while updating the chat.群组相关信息审核没有通过，请检查群名称或群描述中是否存在敏感内容。
400232025Bot ability is not activated.应用未启用机器人能力。你需要登录开发者后台，在应用详情页的 应用能力 > 添加应用能力 页面内，添加 机器人 能力，并发布应用使配置生效。具体操作参见机器人能力。
400232026This name is already used in an existing public chat. Names of public chats are supposed to be different.公开群群名已存在。
400232030Your request specifies a user_id which is invalid.请检查user_id是否正确。
400232031The chat and the new designated chat owner must be in the same tenant.不允许跨租户转让群主，请修改 owner_id 参数，确保对应用户与被操作群组在同一租户内，且用户在群组中。
400232033The operator or invited bots does NOT have the authority to manage external chats without the scope.当前被操作的群为外部群，暂不支持操作外部群。
400232034The app is unavailable or inactivated by the tenant.应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。
400232035Your request specifies an owner_id which is invalid.owner_id 无效，请检查 owner_id 是否正确。
400232037The operator or invited bots does NOT have the authority to manage chat labels without the scope.操作者或受邀的机器人没有权限管理群Label，请检查权限配置。
400232041The avatar key is illegal.群头像 key 非法，请检查后重新输入。可通过上传图片获取头像 key。（注意：上传图片的 ==image_type== 需要指定为 ==avatar==）
400232047The length of the tab name reaches the limit.会话标签页名称过长。
400232057The operator tenant doesn't have the permission to use restricted mode.操作者所属的租户没有权限使用保密模式，请联系租户管理员。保密模式的适用版本与功能介绍，参见会话保密模式。
400232069current chat type unsupported to set public.不支持群类型为公开（public）的外部群。
400232091Due to the security control requirements of this tenant, this tenant does not allow public group.租户管理员设置不允许创建公开群。详情参考管理员管控公开群权限。
400232093This meeting has restricted access. Unable to turn off group membership approval.正在会议中，不支持关闭进群审批（membership_approval），需等会议结束后重试。
400232078The operator tenant doesn't have the permission to use hide_member_count_setting.操作者所属租户无权使用隐藏群成员人数设置。

更多错误码信息，参见通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有