钉钉¶

概述¶

钉钉Channel通过Webhook机器人方式接入，支持向钉钉群组发送消息。

官方文档: https://open.dingtalk.com/document/robots/custom-robot-access
接入方式: Webhook机器人
支持消息类型: 文本、Markdown、链接、卡片

配置参数¶

Config 结构体¶

type Config struct {
    WebhookURL string  // Webhook地址
    Secret     string  // 加签密钥（可选）
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`webhook_url`	string	是	-	钉钉机器人Webhook完整地址
`secret`	string	否	""	加签密钥，用于消息签名验证

webhook_url¶

数据类型: string
格式: https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx
获取方式:
登录钉钉管理后台
进入目标群组 → 群设置 → 智能群助手
添加机器人 → 自定义机器人
复制Webhook地址

secret¶

数据类型: string
格式: 32位字符串，如 SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
获取方式: 创建机器人时选择"加签"安全设置
用途: 用于HMAC-SHA256消息签名，防止伪造请求

完整配置示例¶

YAML配置¶

channels:
  - name: dingtalk-bot
    type: dingtalk
    config:
      webhook_url: "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxx"
      secret: "SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Go代码配置¶

import (
    "github.com/example/gort/pkg/channel/dingtalk"
)

config := dingtalk.Config{
    WebhookURL: "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxx",
    Secret:     "SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}

ch, err := dingtalk.NewChannel("dingtalk-bot", config)
if err != nil {
    log.Fatal(err)
}

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	普通文本
Markdown	✅	支持Markdown格式
链接消息	✅	带缩略图的链接
卡片消息	✅	交互式卡片

能力矩阵¶

GetCapabilities() 返回:
- TextMessages:     true
- MarkdownMessages: true
- ImageMessages:    true
- FileMessages:     true
- AudioMessages:    false
- VideoMessages:    false
- LocationMessages: false
- ReadReceipts:     false
- TypingIndicators: false

常见配置问题¶

问题1: 签名验证失败¶

现象: 发送消息返回"sign not match"

原因: - Secret配置错误 - 系统时间与钉钉服务器时间偏差过大

解决:

// 确保Secret正确
config := dingtalk.Config{
    WebhookURL: "https://oapi.dingtalk.com/robot/send?access_token=xxx",
    Secret:     "SECxxx",  // 必须与钉钉后台一致
}

问题2: access_token无效¶

现象: 返回"token is not exist"

原因: - Webhook URL过期 - 机器人被删除或禁用

解决: 1. 登录钉钉后台重新获取Webhook URL 2. 检查机器人状态是否正常

问题3: IP不在白名单¶

现象: 返回"ip not in whitelist"

原因: 钉钉设置了IP白名单限制

解决: 1. 在钉钉后台添加服务器公网IP到白名单 2. 或关闭IP白名单限制（不推荐生产环境）

安全建议¶

启用加签: 始终配置Secret，启用消息签名验证
IP白名单: 生产环境配置IP白名单
密钥管理: 使用环境变量或密钥管理服务存储Secret
定期轮换: 定期更换机器人并更新配置

错误代码参考¶

错误	说明
`ErrWebhookNotFound`	Webhook URL无效
`ErrInvalidSignature`	签名验证失败
`ErrRateLimited`	触发限流