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

chat-bot：机器人与 Webhook

返回入口：chat.md

适用场景

用于搜索机器人、机器人发送/撤回消息、Webhook 告警、机器人加入/移出群，以及给机器人发单聊消息。

Bot/Webhook 默认统一使用 `dws chat +messages-send`，通过

--as bot|webhook 选择身份；原子发送命令只保留 Shortcut 未发布字段的底层 fallback。

必读约束

• 用户明确要求“用机器人/机器人身份/robot”发送时，使用 dws chat +messages-send --as bot --robot-code <robotCode>；不得改成当前用户身份。
• chat bot search 只返回我创建的机器人，没有 openDingTalkId；给机器人发单聊必须用 chat bot find。
• 机器人发群消息前需确认机器人已在群中；报“机器人不存在”时先 group members add-bot。
• send-by-bot --text 支持 Markdown；需要稳定换行时用空行分隔段落。若以转义形式组织文本，写 \n\n，不要只写 \n。
• recall-by-bot 使用 processQueryKey，不是 openMessageId。
• Bot 多群文本/Markdown 直接使用 +messages-send --groups <cid...> 或 --groups-file <工作目录内相对文件>；最多 100 个稳定 ID，Runtime 去重并返回 im.batch-write.v1 逐目标 ledger。
• Bot/Webhook 没有与 current-user 等价的文件、图片、音视频发送接口；不得把富媒体转成文本 或换身份静默发送。

命令明细

机器人搜索

命令	范围	返回 openDingTalkId	典型触发词
chat bot search	仅当前用户自己创建的机器人	否	“我的机器人”“我创建的机器人”
chat bot find	当前用户可用的全部机器人（含他人/官方）	是	“找机器人”“搜索机器人”“给机器人发单聊”

dws chat bot search --page 1 --size 10 --name "日报"
dws chat bot find --query "日报" --limit 20
dws chat bot find --query "日报" --limit 20 --cursor <nextCursor>

bot find 翻页时 cursor 必须使用上次返回的 nextCursor 字符串原值，不要传 "0" 或数字字面量。

机器人发送与撤回

多群正式入口：

dws chat +messages-send --as bot --robot-code <robot-code> \
  --groups <openConversationId1>,<openConversationId2> \
  --markdown "## 通知\n\n请提交周报" --format json

读取 requestedCount/succeededCount/failedCount/results/failures；unknown 或失败目标不自动重发。

dws chat message send-by-bot（底层 fallback）

普通文本/Markdown、群聊/批量单聊和 @ 已由 +messages-send --as bot 覆盖。只有 Shortcut 缺失真实必需字段且精确 leaf Schema 允许时才使用以下原子命令。

# 群聊
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --title "日报" --text "## 今日完成\n\n- 事项 A\n\n- 事项 B"

# 单聊 userId
dws chat message send-by-bot --robot-code <robot-code> --users userId1,userId2 --title "提醒" --text "请提交周报"

# 单聊 openDingTalkId
dws chat message send-by-bot --robot-code <robot-code> --open-dingtalk-ids openDingTalkId1,openDingTalkId2 --title "提醒" --text "请提交周报"

# 群聊 @ 人
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收"
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 --title "提醒" --text "@openDingTalkId1 @openDingTalkId2 请查收"
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-all --title "通知" --text "请所有人注意"

关键 flags：

Flag	说明
--robot-code	机器人 Code，必填
--group	群聊 openConversationId
--users	单聊 userId 列表，逗号分隔，最多 20 个
--open-dingtalk-ids	单聊 openDingTalkId 列表
--title / --text	消息标题与 Markdown 内容，必填；Markdown 换行用空行，转义表示为 \n\n
--at-user-ids / --at-open-dingtalk-ids	群聊 @ 指定成员，正文需含对应 @id 文本
--at-all	群聊 @所有人

dws chat message recall-by-bot

dws chat message recall-by-bot --robot-code <robot-code> --group <openConversationId> --keys <processQueryKey>
dws chat message recall-by-bot --robot-code <robot-code> --keys key1,key2

群聊撤回传 --group；单聊撤回不传 --group。--keys 来自 send-by-bot 返回的 processQueryKey。

Webhook

默认使用：

dws chat +messages-send --as webhook --webhook-token <webhook-token> --title "告警" --text "CPU 超 90% @10" --at-all

以下是底层 fallback，不作为默认选路：

dws chat message send-by-webhook --token <webhook-token> --title "告警" --text "CPU 超 90% @10" --at-all
dws chat message send-by-webhook --token <webhook-token> --title "test" --text "hi @118785" --at-users 118785

关键规则：

• --token、--title、--text 必填。
• --at-all 时 --text 中需包含 @10。
• --at-users 或 --at-mobiles 时，--text 中需包含对应 @userId 或 @手机号，否则 @ 不生效。

机器人进群

命令	用途	必填参数
group members add-bot	将自定义机器人加入群	--id --robot-code
group members remove-bot	从群移除机器人	--id --bot-id
+chat-bots	查看群内机器人列表	--group <群名或openConversationId>；自然群名内部唯一解析

dws chat group members add-bot --id <openConversationId> --robot-code <robot-code>
dws chat +chat-bots --group "项目群"
dws chat group members remove-bot --id <openConversationId> --bot-id <openBotId>

常见工作流

机器人发消息后撤回

dws chat bot search --name "日报" --format json
dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --title "日报" --markdown "## 今日完成\n\n- 事项 A\n\n- 事项 B" --format json
dws chat message recall-by-bot --robot-code <robot-code> --group <openConversationId> --keys <processQueryKey> --format json

机器人不在群内时先邀请再发送

dws chat bot search --name "日报" --format json
dws chat group members add-bot --id <openConversationId> --robot-code <robot-code> --format json
dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --title "通知" --text "内容" --format json

给机器人发单聊

dws chat bot find --query "玉澜" --format json
dws chat message send --open-dingtalk-id <openDingTalkId> --text "你好" --format json

机器人 @ 指定人

dws aisearch person --keyword "张三" --dimension name --format json
dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --at-user-ids userId1 --title "提醒" --text "@userId1 请查收" --format json

常见错误与回退

• 机器人单聊没有 openDingTalkId：改用 chat bot find，不要用 bot search。
• 机器人发群消息报“机器人不存在”：先 group members add-bot。
• 撤回失败：确认使用 processQueryKey，不是 openMessageId。
• @ 不生效：检查正文是否包含 @userId / @openDingTalkId / @10。
• 需要 Bot 图片/文件/音视频：停止并说明当前身份矩阵不支持；只有用户明确同意改为当前用户身份时，才重新确认目标和内容。