# 更新群信息

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

## 前提条件

应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。

## 使用限制

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

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

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

## 注意事项

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

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/im/v1/chats/:chat_id
HTTP Method | PUT
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 获取与更新群组信息(im:chat)<br>更新群信息(im:chat:update)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>或<br>`user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"

### 路径参数

名称 | 类型 | 描述
---|---|---
chat_id | string | 群 ID。获取方式：<br>- [创建群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/create)，从返回结果中获取该群的 chat_id。<br>- 调用[获取用户或机器人所在的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/list)接口，可以查询用户或机器人所在群的 chat_id。<br>- 调用[搜索对用户或机器人可见的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/search)，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。<br>**注意**：仅支持群模式为 `group` 的群组 ID。你可以调用[获取群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)接口，在返回结果中查看 `chat_mode` 参数取值是否为 `group`。<br>**示例值**："oc_a0553eda9014c201e6969b478895c230"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型<br>**示例值**：open_id<br>**可选值有**：<br>- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>**默认值**：`open_id`<br>**当值为 `user_id`，字段权限要求**：<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
avatar | string | 否 | 群头像对应的 Image Key，可通过[上传图片](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)获取（注意：上传图片的 ==image_type== 需要指定为 ==avatar==）<br>**示例值**："default-avatar_44ae0ca3-e140-494b-956f-78091e348435"
name | string | 否 | 群名称<br>**注意：** <br>- 建议群名称不超过 60 字符<br>- 公开群名称的长度不得少于 2 个字符<br>**示例值**："群聊"
description | string | 否 | 群描述，建议不超过 100 字符<br>**示例值**："测试群描述"
i18n_names | i18n_names | 否 | 群国际化名称，建议不超过 60 字符
zh_cn | string | 否 | 中文名<br>**示例值**："群聊"
en_us | string | 否 | 英文名<br>**示例值**："group chat"
ja_jp | string | 否 | 日文名<br>**示例值**："グループチャット"
add_member_permission | string | 否 | 谁可以添加群成员，群成员包括用户或机器人<br>**可选值有**：<br>- `only_owner`：仅群主和管理员<br>- `all_members`：所有成员<br>**注意**：`add_member_permission` 和 `share_card_permission` 两个参数必须同步配置。<br>- 如果 `add_member_permission` 值为 `only_owner`，则 `share_card_permission` 只能设置为 `not_allowed`。<br>- 如果 `add_member_permission` 值为`all_members`，则 `share_card_permission` 只能设置为 `allowed`。<br>**示例值**："all_members"
share_card_permission | string | 否 | 是否允许分享群<br>**可选值有**：<br>- `allowed`：允许<br>- `not_allowed`：不允许<br>**注意**：`add_member_permission` 和 `share_card_permission` 两个参数必须同步配置。<br>- 如果 `add_member_permission` 值为 `only_owner`，则 `share_card_permission` 只能设置为 `not_allowed`。<br>- 如果 `add_member_permission` 值为`all_members`，则 `share_card_permission` 只能设置为 `allowed`。<br>**示例值**："allowed"
at_all_permission | string | 否 | 谁可以 at 所有人<br>**可选值有**：<br>- `only_owner`：仅群主和管理员<br>- `all_members`：所有成员<br>**示例值**："all_members"
edit_permission | string | 否 | 谁可以编辑群信息<br>**可选值有**：<br>- `only_owner`：仅群主和管理员<br>- `all_members`：所有成员<br>**示例值**："all_members"
owner_id | string | 否 | 新群主的用户 ID，不转让群主时无需填写。ID 类型与查询参数 user_id_type 取值一致，ID 类型推荐使用 OpenID，获取方式可参考文档[如何获取 Open ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)。<br>**示例值**："4d7a3c6g"
join_message_visibility | string | 否 | 成员入群提示消息的可见性<br>**可选值有**：<br>- `only_owner`：仅群主和管理员可见<br>- `all_members`：所有成员可见<br>- `not_anyone`：任何人均不可见<br>**示例值**："only_owner"
leave_message_visibility | string | 否 | 成员退群提示消息的可见性<br>**可选值有**：<br>- `only_owner`：仅群主和管理员可见<br>- `all_members`：所有成员可见<br>- `not_anyone`：任何人均不可见<br>**示例值**："only_owner"
membership_approval | string | 否 | 加群是否需要审批<br>**可选值有**：<br>- `no_approval_required`：无需审批<br>- `approval_required`：需要审批<br>**示例值**："no_approval_required"
restricted_mode_setting | restricted_mode_setting | 否 | 保密模式设置<br>**注意**：保密模式适用于企业旗舰版。适用版本与功能介绍参见[会话保密模式](https://www.feishu.cn/hc/zh-CN/articles/418691056559)。
status | boolean | 否 | 保密模式是否开启<br>**可选值有**：<br>- true：开启。设置为 ture 时，`screenshot_has_permission_setting`、`download_has_permission_setting`、`message_has_permission_setting` 不能全为 `all_members`。<br>- false：不开启。设置为 false 时，`screenshot_has_permission_setting`、`download_has_permission_setting`、`message_has_permission_setting` 不能存在 `not_anyone`。<br>**示例值**：false
screenshot_has_permission_setting | string | 否 | 允许截屏录屏<br>**示例值**："all_members"<br>**可选值有**：<br>- all_members：所有成员允许截屏录屏<br>- not_anyone：所有成员禁止截屏录屏
download_has_permission_setting | string | 否 | 允许下载消息中图片、视频和文件<br>**示例值**："all_members"<br>**可选值有**：<br>- all_members：所有成员允许下载资源<br>- not_anyone：所有成员禁止下载资源
message_has_permission_setting | string | 否 | 允许复制和转发消息<br>**示例值**："all_members"<br>**可选值有**：<br>- all_members：所有成员允许复制和转发消息<br>- not_anyone：所有成员禁止复制和转发消息
chat_type | string | 否 | 群类型<br>**可选值有**：<br>- `private`：私有群<br>- `public`：公开群<br>**示例值**："private"
group_message_type | string | 否 | 群消息形式<br>**示例值**："chat"<br>**可选值有**：<br>- chat：对话消息<br>- thread：话题消息
urgent_setting | string | 否 | 谁可以加急<br>**示例值**："all_members"<br>**可选值有**：<br>- only_owner：仅群主和管理员<br>- all_members：所有成员
video_conference_setting | string | 否 | 谁可以发起视频会议<br>**示例值**："all_members"<br>**可选值有**：<br>- only_owner：仅群主和管理员<br>- all_members：所有成员
hide_member_count_setting | string | 否 | 隐藏群成员人数设置<br>**示例值**："all_members"<br>**可选值有**：<br>- all_members：所有群成员可见<br>- 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"
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-

### 响应体示例
```json
{
    "code": 0,
    "data": {},
    "msg": "success"
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 232001 | Your request contains an invalid request parameter. | 参数错误。请参考 API 文档参数描述，排查请求时参数是否填写有误。
400 | 232002 | No Permission: Only chat owner or admin can edit chat information in the current situation. | 当前只允许群组的群主或群管理员更新群信息。
400 | 232004 | Such an app does NOT exist. | 作为操作者的 app_id 不存在，请联系[技术支持](https://applink.feishu.cn/TLJsX982)。
400 | 232006 | Your request specifies a chat_id which is invalid. | 无效的 chat_id，请检查 chat_id 是否正确。获取方式：<br>- [创建群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/create)，从返回结果中获取该群的 chat_id。<br>- 调用[获取用户或机器人所在的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/list)接口，可以查询用户或机器人所在群的 chat_id。<br>- 调用[搜索对用户或机器人可见的群列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/search)，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
400 | 232008 | Your request specifies a chat whose type is NOT supported currently. | 不支持的群模式（chat_mode）或群类型（chat_type）。你可以调用[获取群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)接口，查看群信息是否符合当前接口的要求。
400 | 232009 | Your request specifies a chat which has already been dissolved. | 群组已被解散，无法操作。
400 | 232010 | Operator and chat can NOT be in different tenants. | 调用接口的操作者和被操作的群组不在同一租户下，无法操作。需确保当前的操作者和被操作的群组在同一租户下。
400 | 232011 | Operator can NOT be out of the chat. | 调用接口的操作者不在群组内，无法操作。你需要将当前调用 API 的应用或用户[加入待操作的群组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/create)后重试。
400 | 232012 | New chat owner can NOT be out of the chat. | 新群主（owner_id）不在群组中，无法操作。你需要[邀请用户入群](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/create)后重试。
400 | 232016 | Non-chat-owner or Non-chat-admin can only edit certain parts. | 非群主或群管理员的普通群成员，只能修改部分群信息 ，包括：群头像（avatar）、群名称（name）、群描述（description）、群国际化名称（i18n_names)。
400 | 232019 | The request has been rate limited. | 触发群限流，请控制请求的速度，详情参见[频控策略](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)。
400 | 232023 | Chat information review failed while updating the chat. | 群组相关信息审核没有通过，请检查群名称或群描述中是否存在敏感内容。
400 | 232025 | Bot ability is not activated. | 应用未启用机器人能力。你需要登录[开发者后台](https://open.feishu.cn/app)，在应用详情页的 **应用能力** > **添加应用能力** 页面内，添加 **机器人** 能力，并发布应用使配置生效。具体操作参见[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。
400 | 232026 | This name is already used in an existing public chat. Names of public chats are supposed to be different. | 公开群群名已存在。
400 | 232030 | Your request specifies a user_id which is invalid. | 请检查user_id是否正确。
400 | 232031 | The chat and the new designated chat owner must be in the same tenant. | 不允许跨租户转让群主，请修改 `owner_id` 参数，确保对应用户与被操作群组在同一租户内，且用户在群组中。
400 | 232033 | The operator or invited bots does NOT have the authority to manage external chats without the scope. | 当前被操作的群为外部群，暂不支持操作外部群。
400 | 232034 | The app is unavailable or inactivated by the tenant. | 应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。
400 | 232035 | Your request specifies an owner_id which is invalid. | owner_id 无效，请检查 owner_id 是否正确。
400 | 232037 | The operator or invited bots does NOT have the authority to manage chat labels without the scope. | 操作者或受邀的机器人没有权限管理群Label，请检查权限配置。
400 | 232041 | The avatar key is illegal. | 群头像 key 非法，请检查后重新输入。可通过[上传图片](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)获取头像 key。（注意：上传图片的 ==image_type== 需要指定为 ==avatar==）
400 | 232047 | The length of the tab name reaches the limit. | 会话标签页名称过长。
400 | 232057 | The operator tenant doesn't have the permission to use restricted mode. | 操作者所属的租户没有权限使用保密模式，请联系租户管理员。保密模式的适用版本与功能介绍，参见[会话保密模式](https://www.feishu.cn/hc/zh-CN/articles/418691056559)。
400 | 232069 | current chat type unsupported to set public. | 不支持群类型为公开（public）的外部群。
400 | 232091 | Due to the security control requirements of this tenant, this tenant does not allow public group. | 租户管理员设置不允许创建公开群。详情参考[管理员管控公开群权限](https://www.feishu.cn/hc/zh-CN/articles/847237870238)。
400 | 232093 | This meeting has restricted access. Unable to turn off group membership approval. | 正在会议中，不支持关闭进群审批（membership_approval），需等会议结束后重试。
400 | 232078 | The operator tenant doesn't have the permission to use hide_member_count_setting. | 操作者所属租户无权使用隐藏群成员人数设置。

更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。