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.shlocated in thisSKILL.mdsibling directory'sscripts/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)
- Identify channel → Determine which channel it belongs to according to api.md "Scenario Routing"
- Validate configuration →
bash scripts/dt_helper.sh --get KEYRead the key values required for that channel - Collect missing items → Ask all at once and
bash scripts/dt_helper.sh --set KEY=VALUEwrite - Obtain Token → For bots use
--token; for work notifications use--old-token; Webhook/sessionWebhook do not require - Execute API → Write multi-line logic into
/tmp/<task>.shthen 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 --nocacheorbash "$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