mcpField
D
dingtalk-message

dingtalk-message

github.com/breath57Productivity1021.6k installsUpdated 18w ago
Repository

About dingtalk-message

dingtalk-message is a skill guide for sending DingTalk messages. It supports workflows targeting groups, individuals, or work notifications, with routing guidance for four channels and instructions for configuration, identity handling, and token use.

Key features

  1. 01Guidance for four DingTalk message channels
  2. 02Scenario-based channel selection
  3. 03Channel-specific configuration checks
  4. 04Distinction between userId and unionId
  5. 05Token retrieval and refresh handling

Use cases

  1. 01Send notifications through a group Webhook
  2. 02Message individuals or groups with a bot
  3. 03Push work notices to employees or departments
  4. 04Reply to callbacks through sessionWebhook

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/breath57/dingtalk-skills --skill dingtalk-message

After installing, type/dingtalk-messagein Claude Code to confirm it loaded.

Bundled filesreferences/api.mdscripts/dt_helper.sh

Details

From the project README

钉钉消息技能

负责钉钉消息发送的所有操作。本文件为策略指南；完整 API 请求格式、场景路由、消息类型速查、身份标识、错误码等见 references/api.md。

dt_helper.sh 位于本 SKILL.md 同级目录的 scripts/dt_helper.sh。

四种消息通道

通道适用场景Token特点
Webhook 机器人往指定群发通知无需最简单；URL 自带凭证
企业内部应用机器人单聊私信 / 群聊--token（新版）可撤回、查已读
工作通知应用推送到"工作通知"--old-token（旧版）可推全员/部门
sessionWebhook回调中直接回复无需回调消息自带临时 URL

工作流程（每次执行前）

  1. 识别通道 → 按 api.md「场景路由」判断属于哪个通道
  2. 校验配置 → bash scripts/dt_helper.sh --get KEY 读取该通道所需键值
  3. 收集缺失项 → 一次性询问并 bash scripts/dt_helper.sh --set KEY=VALUE 写入
  4. 获取 Token → 机器人用 --token；工作通知用 --old-token；Webhook/sessionWebhook 无需
  5. 执行 API → 多行逻辑写入 /tmp/<task>.sh 再执行；禁止 heredoc
各通道所需配置
通道所需配置来源说明
WebhookDINGTALK_WEBHOOK_URL（加签额外需 DINGTALK_WEBHOOK_SECRET）群设置 → 智能群助手 → 添加自定义机器人
机器人消息DINGTALK_APP_KEY + DINGTALK_APP_SECRET开放平台 → 应用管理 → 凭证信息
工作通知DINGTALK_APP_KEY + DINGTALK_APP_SECRET + DINGTALK_AGENT_IDagentId 在应用管理 → 基本信息
  • robotCode = appKey（完全一致，无需额外配置）
  • 凭证禁止在输出中完整打印，确认时仅显示前 4 位 + ****
  • 消息内容缺失时：先询问用户想发什么，不要自行编造
身份标识

消息 API 只接受 userId（staffId），不接受 unionId。详见 grep -A 20 "^## 身份标识" references/api.md。

  • unionId → userId 转换：bash scripts/dt_helper.sh --to-userid <unionId>
  • 群消息发送方式选择：发群消息时须先询问用户用 Webhook 还是企业机器人，详见 grep -A 20 "^### 群消息发送方式选择" references/api.md
执行脚本模板
#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
TOKEN=$(bash "$HELPER" --token)
USER_ID=$(bash "$HELPER" --get DINGTALK_MY_USER_ID | cut -d= -f2)

# 机器人单聊示例
RESP=$(curl -s -w '\nHTTP_STATUS:%{http_code}' -X POST "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend" \
  -H "x-acs-dingtalk-access-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"robotCode":"'$(bash "$HELPER" --get DINGTALK_APP_KEY | cut -d= -f2)'","userIds":["'$USER_ID'"],"msgKey":"sampleText","msgParam":"{\"content\":\"测试消息\"}"}')
echo "$RESP"

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
OLD_TOKEN=$(bash "$HELPER" --old-token)
AGENT_ID=$(bash "$HELPER" --get DINGTALK_AGENT_ID | cut -d= -f2)
USER_ID=$(bash "$HELPER" --get DINGTALK_MY_USER_ID | cut -d= -f2)

# 工作通知示例
RESP=$(curl -s -w '\nHTTP_STATUS:%{http_code}' -X POST "https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=$OLD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"'$AGENT_ID'","userid_list":"'$USER_ID'","msg":{"msgtype":"text","text":{"content":"测试工作通知"}}}')
echo "$RESP"

Token 异常时：bash "$HELPER" --token --nocache 或 bash "$HELPER" --old-token --nocache

references/api.md 查阅索引

grep -A 196 "^## 一、群自定义 Webhook 机器人" references/api.md
grep -A 192 "^## 二、企业内部应用机器人" references/api.md
grep -A 145 "^## 三、工作通知" references/api.md
grep -A 60  "^## 四、sessionWebhook" references/api.md
grep -A 30  "^## 场景路由" references/api.md
grep -A 20  "^### 群消息发送方式选择" references/api.md
grep -A 25  "^## 身份标识" references/api.md
grep -A 30  "^## 消息类型速查" references/api.md
grep -A 33  "^## 错误码" references/api.md
grep -A 12  "^## 所需应用权限" references/api.md

Comments

Markdown supported