钉钉消息技能

负责钉钉消息发送的所有操作。本文件为策略指南，仅包含决策逻辑和工作流程。完整 API 请求格式见文末的

references/api.md

四种消息通道概览

工作流程（每次执行前）

1. 先理解用户意图 → 判断属于哪个消息通道（见下方「场景路由」）
2. 读取配置 → 用一条

   grep -E '^KEY1=|^KEY2='

   命令一次性读取该通道所需的全部键值，不要分多次查询。（跨会话保留，所有 dingtalk-skills 共用同一文件）具体需要哪些配置，见[各通道所需配置](### 各通道所需配置)表格
3. 仅收集该通道所需的缺失配置 → 一次性询问，不要逐条问
4. 持久化 → 写入 config，后续无需再问
5. 执行任务

各通道所需配置

DINGTALK_WEBHOOK_URL

DINGTALK_WEBHOOK_SECRET

DINGTALK_APP_KEY

DINGTALK_APP_SECRET

DINGTALK_APP_KEY

DINGTALK_APP_SECRET

DINGTALK_AGENT_ID

• robotCode

  =

  appKey

  （完全一致，无需额外配置）
• 凭证禁止在输出中完整打印，确认时仅显示前 4 位 +

  ****

执行规范(推荐)

始终使用脚本文件执行：凡是包含变量替换（

$(...)

|

create_file

/tmp/<task>.sh

bash /tmp/<task>.sh

禁止 heredoc（

<<'EOF'

典型脚本模板（读取配置 → 获取 token（带缓存）→ 执行 API）：

#!/bin/bash
set -e
CONFIG=~/.dingtalk-skills/config

# 一次性读取所有所需配置
APP_KEY=$(grep '^DINGTALK_APP_KEY=' "$CONFIG" | cut -d= -f2-)
APP_SECRET=$(grep '^DINGTALK_APP_SECRET=' "$CONFIG" | cut -d= -f2-)

# Token 缓存：有效期内复用，避免重复请求
CACHED_TOKEN=$(grep '^DINGTALK_ACCESS_TOKEN=' "$CONFIG" 2>/dev/null | cut -d= -f2-)
TOKEN_EXPIRY=$(grep '^DINGTALK_TOKEN_EXPIRY=' "$CONFIG" 2>/dev/null | cut -d= -f2-)
NOW=$(date +%s)

if [ -n "$CACHED_TOKEN" ] && [ -n "$TOKEN_EXPIRY" ] && [ "$NOW" -lt "$TOKEN_EXPIRY" ]; then
  TOKEN=$CACHED_TOKEN
else
  RESP=$(curl -s -X POST https://api.dingtalk.com/v1.0/oauth2/accessToken \
    -H 'Content-Type: application/json' \
    -d "{\"appKey\":\"$APP_KEY\",\"appSecret\":\"$APP_SECRET\"}")
  TOKEN=$(echo "$RESP" | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
  EXPIRY=$((NOW + 7000))  # token 有效期 2h，提前约 13 分钟过期
  # 更新缓存（先删旧值再追加）
  sed -i '/^DINGTALK_ACCESS_TOKEN=/d;/^DINGTALK_TOKEN_EXPIRY=/d' "$CONFIG"
  echo "DINGTALK_ACCESS_TOKEN=$TOKEN" >> "$CONFIG"
  echo "DINGTALK_TOKEN_EXPIRY=$EXPIRY" >> "$CONFIG"
fi

# 在此追加具体 API 调用

JSON 字段提取：

grep -o '"key":"[^"]*"' | cut -d'"' -f4

消息内容缺失时的处理

用户未指定消息内容时，不要自行编造，应先询问用户想发送什么内容。仅当用户明确表示"随便发一条测试"时，才使用默认内容：

这是一条来自钉钉机器人的测试消息。

场景路由（收到用户请求后的判断逻辑）

用户想发消息
├─ 发到群里？
│  ├─ 通用群消息（含 @某人）→ 询问用户选择发送方式（见下方「群消息发送方式选择」）
│  ├─ 明确需要撤回或查已读 → 企业机器人群聊（直接跳过询问）
│  └─ 正在处理机器人回调，直接回复 → sessionWebhook
├─ 发给个人？
│  ├─ 以机器人身份发私信 → 企业机器人单聊
│  └─ 以应用身份推工作通知 → 工作通知
├─ 撤回/查已读？
│  ├─ 机器人消息 → 企业机器人的撤回/已读 API
│  └─ 工作通知 → 工作通知的查询/撤回 API
└─ 回复机器人收到的消息？ → sessionWebhook

群消息发送方式选择

用户发起群消息请求时，必须先询问他们选择哪种方式，并说明各自需要什么配置：

请问您想通过哪种方式发这条群消息？

方式	需要提供	如何获取	说明
Webhook 机器人	WEBHOOK_URL	群设置 → 智能群助手 → 添加自定义机器人 → 复制 URL	无需应用权限，配置最简单；支持 @某人（ at.atUserIds ）
企业内部应用机器人	openConversationId （群会话 ID）	机器人收到群消息时，回调体的 conversationId 字段即为该值	需要 APP_KEY / APP_SECRET ；支持撤回、查已读

推荐 Webhook，只需一个 URL 即可，无需任何应用权限。

收到用户选择后按以下方式收集配置：

• 选 Webhook：收集

  DINGTALK_WEBHOOK_URL

  （若启用加签还需

  DINGTALK_WEBHOOK_SECRET

  ），持久化后执行
• 选 企业机器人：收集

  openConversationId

  ，复用已有的

  APP_KEY

  /

  APP_SECRET

  （若未配置则一并收集），调用

  groupMessages/send

执行 API 前按通道获取对应 token：

POST https://api.dingtalk.com/v1.0/oauth2/accessToken

x-acs-dingtalk-access-token

GET https://oapi.dingtalk.com/gettoken?appkey=&appsecret=

?access_token=

token 有效期均为 2 小时，遇 401 重新获取即可。具体请求/返回格式见 api.md 对应章节。

身份标识（关键决策知识）

所有消息发送 API 均只接受 userId（staffId），不接受 unionId。这一点已通过实际 API 调用验证。

userId

staffId

unionId

如何获取 userId

1. 机器人回调（最常用）：消息体的

   senderStaffId

   字段
2. unionId → userId：

   POST /topapi/user/getbyunionid

3. 手机号 → userId：

   POST /topapi/v2/user/getbymobile

4. 管理后台：PC 端钉钉 → 工作台 → 管理后台 → 通讯录

回调消息中的身份字段

senderStaffId

senderUnionId

userId ↔ unionId 互转的 API 细节：

grep -A 8 "^#### userId ↔ unionId" references/api.md

注意

result.unionid

（无下划线）有值，

result.union_id

（有下划线）在部分企业中为空。

消息类型速查

Webhook 消息类型

直接在请求 body 的

msgtype

text

markdown

actionCard

link

feedCard

各类型完整 JSON 格式：

grep -A 30 "^#### 文本消息" references/api.md

（将

文本消息

替换为

Markdown 消息

、

ActionCard

等）

机器人消息类型

通过

msgKey

msgParam

sampleText

content

sampleMarkdown

title

text

sampleActionCard

title

text

singleTitle

singleURL

sampleLink

title

text

messageUrl

picUrl

sampleImageMsg

photoURL

重要：

msgParam

必须是 JSON 字符串，不是对象。完整格式：

grep -A 16 "^### 消息类型" references/api.md

工作通知消息类型

在

msg

msgtype

text

markdown

action_card

注意工作通知的

action_card

用下划线（不同于 Webhook 的

actionCard

）。完整格式：

grep -A 62 "^### 工作通知消息类型" references/api.md

典型场景

"发个群消息通知大家" / "@某人的群消息"

→ 先按「群消息发送方式选择」询问用户用 Webhook 还是企业机器人，收集对应配置后执行。

Webhook 支持 @某人：body 中加

at.atUserIds

（用户 ID 数组），正文同时写

@userId

以高亮显示。

"用 Markdown 发个部署通知到群里"

→ 先询问发送方式（同上），确认选 Webhook 后用

msgtype: markdown

msgKey: sampleMarkdown

"给张三发条消息"

→ 机器人单聊。需

APP_KEY

APP_SECRET

oToMessages/batchSend

"往研发群发个带按钮的消息"

→ 先按「群消息发送方式选择」询问用户用 Webhook 还是企业机器人，收集对应配置后执行。

Webhook 用

msgtype: actionCard

；企业机器人用

msgKey: sampleActionCard

。

"发工作通知给全员"

→ 工作通知。需

APP_KEY

APP_SECRET

AGENT_ID

to_all_user: true

"撤回刚才那条消息"

→ 找到上一次发送返回的

processQueryKey

task_id

"回复机器人收到的消息"

→ sessionWebhook。从回调取

sessionWebhook

错误处理速查

310000 keywords not in content

310000 sign not match

302033 send too fast

invalidStaffIdList

flowControlledStaffIdList

errcode: 88

errcode: 33

完整错误码表：

grep -A 33 "^## 错误码" references/api.md

所需应用权限

Robot.Message.Send

Robot.GroupMessage.Send

Robot.Message.Query

Robot.Message.Recall

Message.CorpConversation.AsyncSend

references/api.md 查阅索引

确定好要做什么之后，用以下命令从

references/api.md

# Webhook 所有消息格式 + 加签计算（196 行）
grep -A 196 "^## 一、群自定义 Webhook 机器人" references/api.md

# 仅加签计算（19 行）
grep -A 19 "^### 加签计算" references/api.md

# 机器人单聊 / 群聊 / 撤回 / 已读 / 身份标识（192 行）
grep -A 192 "^## 二、企业内部应用机器人" references/api.md

# 仅身份标识体系 / userId / unionId（36 行）
grep -A 36 "^#### 钉钉身份标识体系" references/api.md

# 仅 msgKey & msgParam 消息类型表（16 行）
grep -A 16 "^### 消息类型" references/api.md

# 工作通知发送 / 查询 / 撤回（145 行）
grep -A 145 "^## 三、工作通知" references/api.md

# sessionWebhook + 回调消息体（60 行）
grep -A 60 "^## 四、sessionWebhook" references/api.md

# 错误码（33 行）
grep -A 33 "^## 错误码" references/api.md

# 仅某个子章节（将标题替换即可）
grep -A 30 "^#### 文本消息" references/api.md
grep -A 30 "^### 批量发送单聊消息" references/api.md
grep -A 30 "^### 发送工作通知" references/api.md