SuperAPI AI Directory

dingtalk-message

General & other

View repository

Updated 10-15 17:29

About this skill

DingTalk Message Skill

Responsible for all operations of DingTalk message sending. This file isstrategy guide; for the complete API request format, scenario routing, message type quick reference, identity identifiers, error codes, etc., see references/api.md。

dt_helper.sh located in this SKILL.md sibling directory's scripts/dt_helper.sh。

Four message channels

Channel Applicable scenario Token Features
Webhook bot Send notifications to a specified group Not required Simplest; URL carries credentials
Enterprise internal app bot Single chat private message / group chat --token(new version) Can recall, check read status
Work notification App pushes to "Work Notification" --old-token(old version) Can push to all members/departments
sessionWebhook Reply directly in callback Not required Callback message comes with temporary URL

Workflow (before each execution)

  1. Identify channel → Determine which channel it belongs to according to api.md "Scenario Routing"
  2. Validate configuration → bash scripts/dt_helper.sh --get KEY Read the key values required for that channel
  3. Collect missing items → Ask all at once and bash scripts/dt_helper.sh --set KEY=VALUE write
  4. Obtain Token → For bots use --token; for work notifications use --old-token; Webhook/sessionWebhook do not require
  5. Execute API → Write multi-line logic into /tmp/<task>.sh then execute; heredoc prohibited

Configuration required for each channel

Channel Required configuration Source description
Webhook DINGTALK_WEBHOOK_URL(signature additionally requires DINGTALK_WEBHOOK_SECRET) Group Settings → Smart Group Assistant → Add Custom Bot
Bot message DINGTALK_APP_KEY + DINGTALK_APP_SECRET Open Platform → App Management → Credential Information
Work notification DINGTALK_APP_KEY + DINGTALK_APP_SECRET + DINGTALK_AGENT_ID agentId is in App Management → Basic Information
  • robotCode = appKey(completely identical, no additional configuration required)
  • Credentials are prohibited from being printed in full in the output; when confirming, only display the first 4 characters + ****
  • When message content is missing: first ask the user what they want to send, do not make it up yourself

Identity identifiers

The message API only accepts userId (staffId), and does not accept unionId. See grep -A 20 "^## 身份标识" references/api.md。

  • unionId → userId Conversion:bash scripts/dt_helper.sh --to-userid <unionId>
  • Selection of group message sending method: When sending a group message, you must first ask the user whether to use Webhook or an enterprise bot. See grep -A 20 "^### 群消息发送方式选择" references/api.md

Execution script template

#!/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"

When Token is abnormal:bash "$HELPER" --token --nocache or bash "$HELPER" --old-token --nocache

references/api.md lookup index

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