服务端 API/群组/群组管理/更新群信息
# 更新群信息
更新群头像、群名称、群描述、群配置、转让群主等。
**注意事项**：注意事项：
- 应用需要开启[机器人能力](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)
- 对于群主/群管理员 或 创建群组且具备 ==更新应用所创建群的群信息== 权限的机器人，可更新所有信息
- 对于不满足上述权限条件的群成员或机器人：
- 若未开启 ==仅群主和群管理员可编辑群信息== 配置，仅可更新群头像、群名称、群描述、群国际化名称信息
- 若开启了 ==仅群主和群管理员可编辑群信息== 配置，任何群信息都不能修改
- 如果同时更新 ==邀请用户或机器人入群权限== 和 ==群分享权限== 这两项设置需要满足以下条件：
- 若未开启 ==仅群主和管理员可以邀请用户或机器人入群==，需要设置 ==群分享权限== 为 ==允许分享==
- 若开启了 ==仅群主和管理员可以邀请用户或机器人入群==，需要设置 ==群分享权限== 为 ==不允许分享==
## 请求
基本 |
---|---
HTTP URL | https://open.larksuite.com/open-apis/im/v1/chats/:chat_id
HTTP Method | PUT
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 获取与更新群组信息(im:chat)
更新群信息(im:chat:update)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.larksuite.com/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，详情参见[群ID 说明](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-id-description)
**注意**：仅支持群模式为`group`的群组ID
**示例值**："oc_a0553eda9014c201e6969b478895c230"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
avatar | string | 否 | 群头像对应的 Image Key，可通过[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)获取（注意：上传图片的 ==image_type== 需要指定为 ==avatar==）
**示例值**："default-avatar_44ae0ca3-e140-494b-956f-78091e348435"
name | string | 否 | 群名称
**示例值**："群聊"
description | string | 否 | 群描述
**示例值**："测试群描述"
i18n_names | i18n_names | 否 | 群国际化名称
zh_cn | string | 否 | 中文名
**示例值**："群聊"
en_us | string | 否 | 英文名
**示例值**："group chat"
ja_jp | string | 否 | 日文名
**示例值**："グループチャット"
add_member_permission | string | 否 | 邀请用户或机器人入群权限
注意：
- 若值设置为`only_owner`，则share_card_permission只能设置为`not_allowed`
- 若值设置为`all_members`，则share_card_permission只能设置为`allowed`
**可选值有**：
- `only_owner`：仅群主和管理员
- `all_members`：所有成员
**示例值**："all_members"
share_card_permission | string | 否 | 群分享权限
**可选值有**：
- `allowed`：允许
- `not_allowed`：不允许
**示例值**："allowed"
at_all_permission | string | 否 | at 所有人权限
**可选值有**：
- `only_owner`：仅群主和管理员
- `all_members`：所有成员
**示例值**："all_members"
edit_permission | string | 否 | 群编辑权限
**可选值有**：
- `only_owner`：仅群主和管理员
- `all_members`：所有成员
**示例值**："all_members"
owner_id | string | 否 | 新群主 ID，不转让群主时无需填写。ID类型推荐使用 OpenID，获取方式可参考文档[如何获取 Open ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
**示例值**："4d7a3c6g"
join_message_visibility | string | 否 | 入群消息可见性
**可选值有**：
- `only_owner`：仅群主和管理员可见
- `all_members`：所有成员可见
- `not_anyone`：任何人均不可见
**示例值**："only_owner"
leave_message_visibility | string | 否 | 出群消息可见性
**可选值有**：
- `only_owner`：仅群主和管理员可见
- `all_members`：所有成员可见
- `not_anyone`：任何人均不可见
**示例值**："only_owner"
membership_approval | string | 否 | 加群审批
**可选值有**：
- `no_approval_required`：无需审批
- `approval_required`：需要审批
**示例值**："no_approval_required"
restricted_mode_setting | restricted_mode_setting | 否 | 保密模式设置
status | boolean | 否 | 保密模式是否开启。
**注意**：
- status为true时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting不能全为all_members。
- status为false时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting不能存在not_anyone。
**示例值**：false
screenshot_has_permission_setting | string | 否 | 允许截屏录屏
**示例值**："all_members"
**可选值有**：
- all_members：所有成员允许截屏录屏
- not_anyone：所有成员禁止截屏录屏
download_has_permission_setting | string | 否 | 允许下载消息中图片、视频和文件
**示例值**："all_members"
**可选值有**：
- all_members：所有成员允许下载资源
- not_anyone：所有成员禁止下载资源
message_has_permission_setting | string | 否 | 允许复制和转发消息
**示例值**："all_members"
**可选值有**：
- all_members：所有成员允许复制和转发消息
- not_anyone：所有成员禁止复制和转发消息
chat_type | string | 否 | 群类型
**可选值有**：
- `private`：私有群
- `public`：公开群
**示例值**："private"
group_message_type | string | 否 | 群消息形式
**示例值**："chat"
**可选值有**：
- chat：对话消息
- thread：话题消息
urgent_setting | string | 否 | 谁可以加急
**示例值**："all_members"
**可选值有**：
- only_owner：仅群主和管理员
- all_members：所有成员
video_conference_setting | string | 否 | 谁可以发起视频会议
**示例值**："all_members"
**可选值有**：
- only_owner：仅群主和管理员
- all_members：所有成员
hide_member_count_setting | string | 否 | 隐藏群成员人数设置
**示例值**："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"
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
### 响应体示例
```json
{
"code": 0,
"data": {},
"msg": "success"
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 232001 | Your request contains an invalid request parameter. | 参数错误，参考本文档检查输入参数。
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.larksuite.com/TLJsX982)。
400 | 232006 | Your request specifies a chat_id which is invalid. | 无效的 chat_id，请检查chat_id是否正确。
400 | 232008 | Your request specifies a chat whose type is NOT supported currently. | 该群不支持设置为指定的群模式（chat_mode）、群类型（chat_type）或群消息形式（ group_message_type）。
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. | 操作者需要在群组中。
400 | 232012 | New chat owner can NOT be out of the chat. | 新任群主不在群组中。
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.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)。
400 | 232023 | Chat information review failed while updating the chat. | 群组相关信息审核没有通过，请检查群名称或群描述中是否存在敏感内容。
400 | 232025 | Bot ability is not activated. | 应用需要开启[机器人能力](https://open.larksuite.com/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. | 不允许跨租户转让群主。
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是否正确。
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 非法，请检查后重新输入。
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. | 操作者所属的租户没有权限使用保密模式，请联系租户管理员。
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. | 因租户安全管控，不支持创建公开群，请联系租户管理员。
400 | 232093 | This meeting has restricted access. Unable to turn off group membership approval. | 正在会议中，不支持关闭进群验证。
400 | 232078 | The operator tenant doesn't have the permission to use hide_member_count_setting. | 操作者所属租户无权使用隐藏群成员人数设置。