SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdingtalk-message

dingtalk-message

Office & productivity

View repository

Updated 10-25 04:53

About this skill

DingTalk Message Sending Skill

Overview

Supports two access methods:

  • Webhook custom robot: sends messages to group chats via access_token, simple to set up
  • Enterprise internal robot: sends one-on-one and group chat messages via app_key/app_secret, with fuller functionality

Supports multi-robot management; when there is only one, it is used automatically; when there are multiple, one is automatically selected by priority.

Environment Requirements

  • Python 3.7+
  • pip install requests

Initial Configuration

Guided Flow

When using this skill for the first time, you must guide the user through the following flow to complete configuration:

  1. Ask the user for the robot type and credential information：

    • Webhook robot: requires access_token(and optionally a signing secret secret）
    • Enterprise internal robot: requires app_key、app_secret、robot_code(and optionally agent_id）

  2. Execute the configuration command：python scripts/dingtalk.py robot-add --name "机器人名" --type webhook ...

  3. Verify the configuration：python scripts/dingtalk.py config --show

Configuration File Paths

Configuration is stored centrally in the system configuration directory, shared by all AI agents, with no need to configure repeatedly:

Platform Configuration File State File
macOS / Linux ~/.config/dingtalk/config.json ~/.config/dingtalk/state.json
Windows %APPDATA%\dingtalk\config.json %APPDATA%\dingtalk\state.json

Manually Editing the Configuration File

You can also edit the configuration file directly; each robot is identified by name (it is recommended to use meaningful names such as group name or purpose), anddescription describes the purpose for easy intelligent matching:

{
    "default_robot": "技术告警群",
    "robots": [
        {
            "name": "技术告警群",
            "type": "webhook",
            "description": "发送技术告警到后端技术群",
            "webhook_token": "你的access_token",
            "webhook_secret": ""
        },
        {
            "name": "内部通知机器人",
            "type": "app",
            "description": "企业内部机器人，支持单聊和群聊",
            "app_key": "你的AppKey",
            "app_secret": "你的AppSecret",
            "robot_code": "你的机器人编号",
            "agent_id": ""
        }
    ]
}

webhook_token Just fill in access_token, and the script automatically assembles the complete URL.

Add via Command Line

# 添加 Webhook 机器人
python scripts/dingtalk.py robot-add --name "技术告警群" --type webhook --webhook-token "access_token_xxx" --desc "发送告警到后端技术群"

# 添加企业内部机器人
python scripts/dingtalk.py robot-add --name "内部通知" --type app --app-key dingxxx --app-secret xxx --robot-code robot-xxx --desc "支持单聊群聊"

Verify Configuration

python scripts/dingtalk.py config --show

Robot Management

Selection Logic

  • When only one robot is configured, it is used automatically
  • When there are multiple robots:--robot specified > default_robot > most recently used > first available
  • When the user has not explicitly specified one, intelligent matching can be performed based on the robot's description and recent message records, or the user can be asked

Management Commands

# 添加（--desc 描述用途，便于记忆和智能选择）
python scripts/dingtalk.py robot-add --name "技术告警群" --type webhook --webhook-token "access_token_xxx" --desc "发送告警到后端技术群"
python scripts/dingtalk.py robot-add --name "内部通知" --type app --app-key dingxxx --app-secret xxx --robot-code robot-xxx --desc "企业内部机器人，支持单聊群聊"

# 查看所有机器人（含描述、使用次数、最近消息）
python scripts/dingtalk.py robot-list

# 更新描述 / 重命名
python scripts/dingtalk.py robot-update --name "技术告警群" --desc "后端+SRE告警群"
python scripts/dingtalk.py robot-update --name "alert-bot" --rename "技术告警群"

# 指定机器人发送
python scripts/dingtalk.py webhook-text --robot "技术告警群" "告警消息"

# 设置默认 / 启用禁用 / 删除
python scripts/dingtalk.py robot-default --name "产品日报群"
python scripts/dingtalk.py robot-enable --name "技术告警群" --disable
python scripts/dingtalk.py robot-remove --name "技术告警群"

Usage Records

Each time a message is sent, a summary is automatically recorded to the state file, including:

  • Usage count, most recent usage time, most recent status
  • Summaries of the most recent 10 messages (message type + first 60 characters of content)

Can be viewed via robot-list , and is also used for intelligent robot selection.

Webhook Messages

Webhook commands start with the webhook- prefix. How to get the Webhook URL: DingTalk group > Group Settings > Smart Group Assistant > Add Custom Robot > Copy Webhook Address

Text Message

# 已配置时直接发送
python scripts/dingtalk.py webhook-text "消息内容"

# 临时指定 token（无需配置）
python scripts/dingtalk.py webhook-text --webhook-token "access_token_xxx" "消息内容"

# @用户 / @所有人
python scripts/dingtalk.py webhook-text --at-mobiles 13800138000 "消息 @13800138000"
python scripts/dingtalk.py webhook-text --at-all "全员通知"

Markdown Message

python scripts/dingtalk.py webhook-markdown \
    --title "天气提醒" \
    "#### 杭州天气\n> 9度，西北风1级"

Link Message

python scripts/dingtalk.py webhook-link \
    --title "时代在进步" \
    --url "https://www.dingtalk.com" \
    --pic-url "https://example.com/image.png" \
    "点击查看详情"

ActionCard Message

# 单按钮
python scripts/dingtalk.py webhook-action-card \
    --title "审批通知" \
    --single-title "查看详情" \
    --url "https://www.dingtalk.com" \
    "#### 请假申请\n请审批"

# 多按钮
python scripts/dingtalk.py webhook-action-card \
    --title "审批通知" \
    --buttons "同意,https://approve.com/yes;拒绝,https://approve.com/no" \
    --btn-orientation 0 \
    "#### 请假申请"

FeedCard Message

python scripts/dingtalk.py webhook-feed-card \
    --links "新闻1,https://news1.com,https://img1.com/pic.png;新闻2,https://news2.com,https://img2.com/pic.png"

Signing Security

# 配置加签密钥（一次设置）
python scripts/dingtalk.py config --set webhook_secret=SECxxxxxxxxxxxxxxxxxxxxxxxxxx

# 或通过参数临时指定
python scripts/dingtalk.py webhook-text \
    --webhook-token "access_token_xxx" \
    --webhook-secret "SECxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    "带加签的消息"

Enterprise Internal Robot Messages

One-on-One Message

# 文本
python scripts/dingtalk.py text "Hello!" --users user001,user002

# Markdown
python scripts/dingtalk.py markdown --title "天气提醒" --users user001 \
    "#### 杭州天气\n> 9度，西北风1级"

# 链接
python scripts/dingtalk.py link --title "时代在进步" --url "https://www.dingtalk.com" \
    --users user001 "点击查看详情"

# ActionCard
python scripts/dingtalk.py action-card --title "审批通知" \
    --single-title "查看详情" --url "https://www.dingtalk.com" \
    --users user001 "#### 请假申请\n请审批"

# 文件
python scripts/dingtalk.py file --users user001 --file /path/to/report.pdf --file-name "月度报告.pdf"

Group Chat Message

python scripts/dingtalk.py text "大家好！" \
    --mode group \
    --conversation-id chatxxxxxxxxxxxxxxxx \
    --at-mobiles 13800138000,13900139000

CLI Syntax Rules

  1. content is a positional argument (without the -- prefix), placed after optional arguments
  2. Use \nfor line breaks; the script automatically handles conversion
  3. content must be wrapped in double quotes
  4. Can be viewed via --app-key、--robot-code and other parameters temporarily override the configuration file

DingTalk Markdown syntax limitations

DingTalk Markdown only supports a limited subset; the following must be observed when constructing content:

Supported: headings (#), bold (**), links ([](url)), images (![](url)), unordered lists (-), ordered lists (1.), quotes (>)

Not supported (prohibited): horizontal rules (---), tables, code blocks, inline code, strikethrough, task lists, italics, nested lists

The script automatically removes horizontal rules ---, but other unsupported syntax must be avoided manually.

Common error codes

Enterprise internal bot: 40001 (token expired) / 40004 (invalid bot) / 40009 (user not in visible scope) / 40010 (no session established) / 40037 (sending too frequently)

Webhook： 300001 (invalid token) / 310000 (signature verification failed) / 302503 (rate limit, 20 messages per minute)

Notes

  • Rate limits: enterprise internal bot 20 times per second, Webhook 20 messages per minute
  • Webhook group chats only: one-on-one chats are not supported; link/feedCard do not support the @ feature
  • Prerequisite for one-on-one chats: the user must have first sent a message to the bot
  • Batch limits: at most 100 users per send
  • Message length: for overly long content, it is recommended to split it or send it as a file