钉钉自定义机器人

钉钉自定义机器人适合固定群聊通知。本文依据钉钉开放平台资料整理，核验日期为 2026-09-14；未使用真实组织完成发送验证。

能力边界

问题	结论
能发到哪里	发送到创建机器人的固定群聊，Webhook 不能临时指定另一个群
能否接收群消息	不能；需要双向消息时使用企业机器人对话
是否需要应用凭据	群自定义机器人不使用企业应用 AppKey，但 Webhook 中的 Access Token 本身就是凭据
支持哪些安全方式	自定义关键词、IP 地址段和加签，具体可用项以群创建页面为准
外部群能否添加	取决于群类型、组织策略和客户端入口；没有添加入口时不能从开发者后台绕过

需要按员工、部门或全员触达时使用企业工作通知，不要为大量群分别散发 Webhook 代替组织级应用。

准备条件

1. 当前账号已经加入目标群，并确认该群允许添加自定义机器人。
2. 在群设置的机器人管理中能看到添加入口；组织安全策略没有禁用该能力。
3. 已确定关键词、IP 白名单或加签策略。生产环境优先加签，并叠加稳定出口 IP。
4. 发送端可通过 HTTPS 访问 oapi.dingtalk.com，服务器时间保持同步。
5. 有服务端 Secret 管理位置，不把 Webhook 和加签 Secret 放进浏览器或公开配置。

如何判断自己有没有权限

在钉钉客户端打开目标群，进入群设置 → 机器人 → 添加机器人：

• 能选择自定义机器人并完成安全设置：当前账号具备实际添加权限。
• 能看到已有机器人但没有添加按钮：请群主或群管理员检查群管理权限和组织策略。
• 完全没有机器人入口：先确认群类型、客户端版本和组织是否允许该能力。
• 创建时提示组织限制：由组织管理员调整策略，修改调用代码不会解决。

群主、群管理员和普通成员的最终能力可能受组织策略影响，因此以目标群的实际页面为准。

配置步骤

1. 在群内创建

1. 打开目标群设置，进入机器人管理并添加自定义机器人。
2. 填写机器人名称和说明，名称中区分测试、预发布和生产用途。
3. 选择安全设置并保存。不要在完全无安全限制的状态下直接接入生产告警。
4. 复制包含 access_token 的完整 Webhook。

2. 配置安全方式

• 关键词：消息文本必须包含至少一个已配置关键词。Markdown 和卡片也要确认关键词出现在平台实际检查的文本字段中。
• IP 地址段：填写实际公网出口 IP 或网段，不是开发机、容器或 Pod 的内网地址。
• 加签：保存以 SEC 开头的 Secret，使用毫秒时间戳与 Secret 按官方 HMAC-SHA256 规则生成 sign，再对签名做 URL 编码。

3. 最小验证

1. 在服务端保存 Webhook 和 Secret。
2. 先发送包含安全关键词的纯文本消息。
3. 检查 HTTP 状态和响应 errcode，成功值为 0。
4. 在目标群确认机器人名称和消息内容正确。

Web 页面能否完成配置

钉钉开放平台控制台用于管理企业应用和企业机器人，不能替代群内自定义机器人的创建。群自定义机器人需要在目标群客户端的机器人管理中完成；官方文档地址只提供说明，不是配置入口。

凭据说明

字段	必需	说明
WEBHOOK_URL	是	包含机器人 Access Token 的完整地址
SIGNING_SECRET	启用加签时	以 SEC 开头的签名密钥
KEYWORD	启用关键词时	消息中必须出现的安全关键词

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

curl

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"text","text":{"content":"通知渠道连通性测试"}}'

JavaScript

const response = await fetch(process.env.WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msgtype: 'text',
    text: { content: '通知渠道连通性测试' },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
if (result.errcode !== 0) throw new Error(JSON.stringify(result));
console.log(result);

Python

import os
import requests

response = requests.post(
    os.environ["WEBHOOK_URL"],
    json={"msgtype": "text", "text": {"content": "通知渠道连通性测试"}},
    timeout=15,
)
response.raise_for_status()
result = response.json()
if result.get("errcode") != 0:
    raise RuntimeError(result)
print(result)

开启加签后，将按当前毫秒时间和 Secret 生成的 timestamp、sign 参数加入 Webhook 查询字符串。签名算法不能复用飞书或其他平台实现；先用官方示例验证固定输入，再接系统时间。

验证结果

检查响应 errcode=0，并确认目标群收到文本。随后再测试 Markdown、链接或卡片，不要一开始就使用复杂消息体。errcode=310000 常见于关键词、IP、签名或时间戳等安全校验失败，具体原因以 errmsg 为准。

消息与频率限制

• 官方文档当前对自定义机器人实施发送频率限制，常见上限为每个机器人每分钟 20 条；实际限制和错误提示以当前官方页面为准。
• 高频告警要先聚合、抑制和分级，不能创建多个机器人规避平台频率控制。
• Markdown、链接、ActionCard、FeedCard 等消息体字段不同，纯文本成功后再逐类接入。
• @ 成员需要使用平台支持的手机号或用户标识字段，并受群成员范围限制。

安全建议

• Webhook、Access Token 和 Secret 均按密钥处理。
• 加签请求要限制时间戳偏移，发送服务器应保持时间同步。
• 泄露后立即重置或删除机器人，并更新调用方配置。
• IP、关键词和加签可以叠加，但都不能替代 Webhook 保密。
• 限流时有限退避；安全校验和参数错误直接停止重试并告警。

常见问题

关键词错误：消息正文没有包含已配置关键词。

签名错误：检查时间戳单位、URL 编码和 HMAC-SHA256 计算顺序。

发送频率受限：按返回码退避，不要对参数错误持续重试。

群里没有机器人入口：检查群类型、当前账号的群管理权限和组织策略。开发者后台不能绕过群内权限。

外部群无法添加：以目标群客户端入口为准；没有入口时改用该群允许的应用机器人或其他渠道。

返回 310000：读取 errmsg，逐项检查关键词、真实出口 IP、时间戳单位、签名和 URL 编码。

官方资料

• 钉钉开放平台：自定义机器人接入
• 钉钉开放平台控制台