dingtalk-workspace-cli/skills/multi/dingtalk-chat/references/chat/chat-group.md

chat-group：群聊、成员、设置与群身份

返回入口：chat.md

适用场景

用于群搜索、建群、成员增删、机器人进群、群设置、群主转让、群邀请分享、群公告、入群审批、群身份和群禁言。

基础建群默认使用 `dws chat +chat-create`：已知成员 ID 传

--users，姓名/花名传 --member-query；群主默认当前用户，也可传 --owner-open-dingtalk-id 或 --owner-query。全部自然身份唯一解析并去重后才执行一次创建。

必读约束

• 群聊目标统一使用 openConversationId。只有数字群号时，先用 chat group get-by-group-id 转换。
• 群搜索唯一推荐 dws chat +chat-search --query <群名>；chat search、chat group search、 +chat-group-search 和 +search-group 仅是兼容拼法，不应被写成并列默认路线。
• 群成员操作中，--users 常为逗号分隔列表；具体要求以命令 --help 为准。
• 解散群、踢人、转让群主、禁言、管理员设置都是高影响操作，执行前必须确认目标群和用户。
• 发布或修改群公告会触达群成员；公告正文是 Markdown，定时公告 --run-at 建议带时区。

命令明细

搜索与基础信息

命令	用途	示例与要点
+chat-search	按关键词搜索群聊	dws chat +chat-search --query "项目冲刺" --limit 20 --cursor 0；多候选必须消歧
chat search-common	搜索共同群	dws chat search-common --nicks "风雷,山乔" --match-mode AND --limit 20 --cursor 0
chat group get-by-group-id	数字群号转 openConversationId	dws chat group get-by-group-id --group-id 12345678
+chat-bots	查看群内所有机器人	dws chat +chat-bots --group <群名或openConversationId>；内部唯一解析自然群名

search-common 中 --match-mode AND 表示所有人都在群里，OR 表示任一人在群里。

群创建与基础操作

dws chat group create（底层 fallback）

只有需要 +chat-create 尚未发布的底层字段时才评估原子创建命令，并先读取精确 leaf Schema。+chat-create 已支持 --thread 和显式群主；普通内部/外部群创建不得回流到手工 aisearch → group create 链路。

dws chat group create --name "Q1 项目冲刺群" --users userId1,userId2,userId3
dws chat group create --name "外部合作群" --users userId1,userId2 --type EXTERNAL
dws chat group create --name "话题圈" --users userId1,userId2 --thread

关键 flags：

Flag	说明
--name	群名称，必填
--users	成员 userId 或 openDingTalkId，逗号分隔，必填
--type	INTERNAL / EXTERNAL / NORMAL，默认 INTERNAL
--thread	开启话题模式，创建话题圈

创建成功后提取 openConversationId，用于发消息、成员管理、群设置。

命令	用途	必填参数
group rename	更新群名称	--id --name；只知群名时先用 +chat-search --query <群名> 唯一解析 ID，不猜 +chat-rename
group quit	当前用户退出群聊	--group
group dismiss	解散群聊，不可逆	--group

成员与机器人

命令	用途	示例
+chat-members-list	全量查看群成员并分桶用户/机器人	--group <群名或openConversationId>；显式 ID 也可用 --conversation-id，检查 buckets/complete/failures
group members add	添加群成员	dws chat group members add --id <openConversationId> --users userId1,userId2
group members remove	移除群成员	dws chat group members remove --id <openConversationId> --users userId1,userId2
group members list-by-ids	按 openDingTalkId 批量查成员详情	dws chat group members list-by-ids --id <openConversationId> --users openDingTalkId1,openDingTalkId2
group members add-bot	将自定义机器人加入群	dws chat group members add-bot --id <openConversationId> --robot-code <robot-code>
group members remove-bot	从群内移除机器人	dws chat group members remove-bot --id <openConversationId> --bot-id <openBotId>

机器人发群消息如果报“机器人不存在”，先 group members add-bot 再重发。

群设置与权限

命令	用途	必填参数
group transfer-owner	转让群主	--group + --user(userId) 或 --new-owner(openDingTalkId)
group upgrade-to-external	将普通群升级为外部群（不可逆，需先确认）	--group --yes；可选 --extension（拓展字段）
+chat-invite-url	获取群邀请链接	--group <群名或openConversationId> 或 --chat-query <群名>；可选 --expires-seconds
group share-invite	将指定群的邀请链接分享到另一个会话或单聊用户	--source + --target / --receiver 二选一
group update-icon	更新群头像	--group --icon-media-id
group update-settings	更新管理员级别的群功能开关	--group --setting-key --status
group user-settings query	批量查询当前用户自己的群会话设置	--groups
group user-settings set	批量更新当前用户自己的群会话设置	--items
group update-nick	设置或清除当前用户群昵称	--group，可选 --nick；不传则清除群昵称
group update-alias	设置当前用户群备注	--group --alias-title
group set-history	设置新成员可查看历史消息范围	--group --option
group get-mute-config	查询群用户禁言配置	--group
group-mute	全员禁言/解除全员禁言	--group，默认禁言，--off 解除
group-mute-member	指定成员禁言/解除禁言	--group --user/--users；禁言需 --mute-time
group set-admin	设置/取消管理员	--group --user/--users；--off 取消

update-settings 是管理员级别的群功能开关操作，常用 settingKey：authority、joinValidation、onlyAdminCanAtAll、searchable、addFriendForbidden、onlyAdminCanDING、onlyAdminCanPinMsg、onlyAdminCanSendFile、groupEmailDisabled、groupLiveAuthority、groupBillAuthority。

group user-settings 是当前登录用户自己的群会话设置批量入口（置顶、免打扰、群昵称、群备注等），不是管理员级别的群功能开关；单个群昵称/群备注仍优先使用 group update-nick / group update-alias，管理员级别的群功能开关继续使用 group update-settings。

group user-settings set --items 传 JSON 数组，每个元素表示一个群会话的当前用户设置。字段含义：

字段	含义	值说明
openConversationId	群会话 ID	必填，来自 chat search / group list-all 等真实返回
top	当前用户是否置顶该群会话	true=置顶，false=取消置顶
mute	当前用户是否开启该群会话免打扰	true=开启免打扰，false=关闭免打扰
groupNick	当前用户在该群里的群昵称	字符串；空字符串表示清空昵称
groupAlias	当前用户给该群设置的备注	字符串；空字符串表示清空备注

只传本次要改的字段；不要补用户没要求修改的字段。批量设置多个群时，items 放多个对象。

group-mute-member --mute-time 单位毫秒，常用值：300000、3600000、86400000、604800000、2592000000。

group share-invite 的 --source 是被分享群的 openConversationId；--target 是接收分享消息的会话，--receiver 是接收分享消息的单聊用户 openDingTalkId，二者必须二选一。

dws chat group share-invite --source <sourceOpenConversationId> --target <targetOpenConversationId>
dws chat group share-invite --source <sourceOpenConversationId> --receiver <receiverOpenDingTalkId>
dws chat group share-invite --source <sourceOpenConversationId> --target <targetOpenConversationId> --expires-seconds 86400 --uuid <uuid>
dws chat group user-settings query --groups <openConversationId1>,<openConversationId2>
dws chat group user-settings set --items '[{"openConversationId":"cid1","top":true,"mute":false}]'

群公告

群公告正文使用 Markdown。支持标题、加粗、斜体、删除线、行内代码、链接、代码块、列表、表格、引用、分割线、图片、段落和换行；下划线、字体色、背景色、字号属于编辑器专属能力，无法通过 Markdown 表达。

命令	用途	必填参数
group notice create	发布群公告，支持置顶、DING 和定时发布	--group --content
group notice edit	整体替换指定群公告内容	--group --notice-id --content
group notice get	查询单条群公告详情	--group --notice-id
group notice list	分页拉取群公告列表	--group

dws chat group notice create --group <openConversationId> --content "今晚 22 点系统维护，请提前保存工作内容"
dws chat group notice create --group <openConversationId> --content "# 重要通知\n\n请大家查收" --sticky --send-ding
dws chat group notice create --group <openConversationId> --content "明早九点例会" --run-at "2026-07-03T09:00:00+08:00"
dws chat group notice list --group <openConversationId> --limit 20 --cursor <nextPageCursor>
dws chat group notice get --group <openConversationId> --notice-id <dataId>
dws chat group notice edit --group <openConversationId> --notice-id <dataId> --content "更新后的公告内容"

注意事项：

• notice edit 会整体替换原公告正文，必须传完整的新内容。
• notice list --scheduled 查询尚未到发布时间的定时公告；默认查询已发布公告。
• hasMore=true 时，用返回的 nextPageCursor 继续翻页。
• notice get 返回正文摘要、置顶状态、发布者、已读人数/应收人数、点赞/评论数、是否可编辑、是否已读、是否定时公告等信息。

群列表与入群审批

命令	用途	示例与要点
group list-my-groups	拉取我创建/管理的群	可选 --role OWNER/ADMIN、--limit、--exclude-muted
group list-all	分页拉取我加入的所有群	--limit 默认 100，最大 200；翻页用 nextCursor
group list-join-validations	拉取入群验证记录	包括自己被拒绝的记录以及作为审批者的记录
group audit-join-validation	审批入群验证	--group --record-id --applicant --inviter --status

审批动作 --status：AuditApprove、AuditDelete、AuditIgnore、AuditRefuse、AuditBlock。

dws chat group list-join-validations --limit 20
dws chat group audit-join-validation --group <openConversationId> --record-id 123456 --applicant <openDingTalkId> --inviter <openDingTalkId> --status AuditApprove

群身份

chat group-role 管理群内自定义身份标签。

命令	用途	必填参数
group-role list	查看群身份列表	--group
group-role add	新增群身份	--group --name
group-role update	修改群身份名称	--group --role-id --name
group-role remove	删除群身份	--group --role-id
group-role set-user	覆盖用户全部群身份，空 --role-ids 表示清除	--group --user --role-ids
group-role remove-user	移除用户指定群身份	--group --user --role-ids
group-role query-user	查询用户当前群身份	--group --user

openRoleId 来自 group-role list 返回。

常见工作流

搜索群并发消息

dws chat +send-to-group --group "项目冲刺" --text "请大家看一下最新进展" --format json

建群并拉人

dws chat +chat-create --name "Q1 项目冲刺群" --member-query "张三,李四" --format json
dws chat +chat-create --name "合作群" --member-query "张三,李四" --owner-query "王五" --format json
dws chat group members add --id <openConversationId> --users userId3,userId4 --format json

分享群邀请并发布公告

dws chat group share-invite --source <sourceOpenConversationId> --target <targetOpenConversationId> --format json
dws chat group notice create --group <openConversationId> --content "# 项目公告\n\n请大家关注最新安排" --send-ding --format json

设置管理员并禁言成员

dws chat group set-admin --group <openConversationId> --users userId1,userId2 --format json
dws chat group-mute-member --group <openConversationId> --users userId3 --mute-time 3600000 --format json

常见错误与回退

• 只有数字群号：先 group get-by-group-id，不要直接当 --group。
• 找不到群：使用 +chat-search --query 扩大关键词；零命中或多候选时停止，不臆测 openConversationId。
• 入群审批缺参数：从 group list-join-validations 提取 record-id、applicant、inviter。
• 机器人进群失败：确认当前用户有群管理权限。
• 分享群邀请目标不明确：--target 和 --receiver 只能二选一，先确认是发到群/会话还是发给个人。
• 修改公告前没有完整新正文：先向用户确认完整公告内容，不要只传增量片段。