dingtalk

钉钉群机器人消息发送包

这是一个用于向钉钉群发送消息的 Go 语言包，支持多种消息类型。

功能特性

• ✅ 文本消息
• ✅ Markdown 消息
• ✅ 链接消息
• ✅ ActionCard 消息（单按钮/多按钮）
• ✅ FeedCard 消息（多条链接展示）
• ✅ 支持 @人功能（text、markdown类型完全支持，其他类型为扩展预留）
• ✅ 加签安全验证
• ✅ 完善的错误处理
• ✅ 详细的日志记录

@人功能说明

根据钉钉官方文档：

• ✅ text（文本） 和 markdown 类型消息完全支持@人功能
• ⚠️ link（链接）、actionCard 和 feedCard 类型消息官方不支持@人功能

本包为所有消息类型都提供了@人参数，对于官方不支持的类型，@人字段会被发送但可能不会生效。这样设计是为了：

1. 保持API的一致性
2. 如果钉钉未来支持这些类型的@人功能，代码无需修改即可使用

安装

go get gitee.com/hexug/go-tools/msgbot/dingtalk

快速开始

1. 创建客户端

import "gitee.com/hexug/go-tools/msgbot/dingtalk"

// 创建默认客户端
client := dingtalk.NewClient()

// 或创建指定日志级别的客户端
client := dingtalk.NewClientWithLogLevel(dingtalk.LogLevelDebug)

2. 使用加签方式（推荐）

钉钉机器人支持三种安全设置方式：自定义关键词、加签、IP地址。推荐使用加签方式，更加安全。

// 原始webhook和secret
webhook := "https://oapi.dingtalk.com/robot/send?access_token=xxx"
secret := "SECxxxxxxxxxxxx" // 创建机器人时获得的加签密钥

// 生成带签名的URL
signedURL, err := dingtalk.GenerateSignedURL(webhook, secret)
if err != nil {
    log.Fatal(err)
}

// 使用签名后的URL发送消息
ctx := context.Background()
err = client.SendWebhookTextMessage(ctx, signedURL, "这是一条测试消息")

3. 发送文本消息

ctx := context.Background()
webhookUrl := "YOUR_DINGTALK_WEBHOOK_URL"

// 简单文本消息
err := client.SendWebhookTextMessage(ctx, webhookUrl, "这是一条测试消息")

// 带@功能的文本消息
req := &dingtalk.SendTextRequest{
    Webhook:   webhookUrl,
    Content:   "这是一条测试消息，@所有人",
    AtMobiles: []string{"13800138000"},
    IsAtAll:   true,
}
err := client.SendWebhookTextMessageV2(ctx, req)

3. 发送文本消息

ctx := context.Background()
webhookUrl := "YOUR_DINGTALK_WEBHOOK_URL"

// 简单文本消息
err := client.SendWebhookTextMessage(ctx, webhookUrl, "这是一条测试消息")

// 带@功能的文本消息
req := &dingtalk.SendTextRequest{
    Webhook:   webhookUrl,
    Content:   "这是一条测试消息，@所有人",
    AtMobiles: []string{"13800138000"},
    IsAtAll:   true,
}
err := client.SendWebhookTextMessageV2(ctx, req)

4. 发送 Markdown 消息

markdown := `## 测试标题
这是一条测试Markdown消息

### 功能列表
- 功能1
- 功能2
- 功能3

**加粗文本** *斜体文本*`

// 简单Markdown消息
err := client.SendWebhookMarkdownMessage(ctx, webhookUrl, "测试标题", markdown)

// 带@功能的Markdown消息
req := &dingtalk.SendMarkdownRequest{
    Webhook:   webhookUrl,
    Title:     "测试标题",
    Text:      markdown,
    AtMobiles: []string{"13800138000"},
    IsAtAll:   false,
}
err := client.SendWebhookMarkdownMessageV2(ctx, req)

5. 发送链接消息

// 简单链接消息
err := client.SendWebhookLinkMessage(
    ctx,
    webhookUrl,
    "消息标题",
    "消息内容描述",
    "https://www.example.com",
    "https://example.com/image.png", // 图片URL（可选）
)

// 使用请求对象
req := &dingtalk.SendLinkRequest{
    Webhook:    webhookUrl,
    Title:      "消息标题",
    Text:       "消息内容描述",
    MessageUrl: "https://www.example.com",
    PicUrl:     "https://example.com/image.png",
}
err := client.SendWebhookLinkMessageV2(ctx, req)

6. 发送包含代码块的 Markdown 消息

// JSON代码块
data := map[string]interface{}{
    "name": "张三",
    "age":  30,
}
jsonBytes, _ := json.MarshalIndent(data, "", "  ")
markdown := fmt.Sprintf("## 数据\n\n```json\n%s\n```", string(jsonBytes))
err := client.SendWebhookMarkdownMessage(ctx, webhookUrl, "数据展示", markdown)

// Go代码块
goCode, _ := os.ReadFile("main.go")
markdown := fmt.Sprintf("## 代码\n\n```go\n%s\n```", string(goCode))
err := client.SendWebhookMarkdownMessage(ctx, webhookUrl, "代码展示", markdown)

7. 发送 ActionCard 消息

ActionCard 消息支持单按钮和多按钮两种模式。

// 单按钮模式
text := `#### 系统维护通知

![screenshot](https://example.com/image.png)

### 重要提醒
- 系统将于今晚22:00进行维护
- 预计维护时间：2小时

**请提前保存工作！**`

err := client.SendWebhookActionCardMessage(
    ctx,
    webhookUrl,
    "系统维护通知",
    text,
    "查看详情",
    "https://www.example.com",
    "0", // 0-按钮竖直排列，1-按钮横向排列
)

// 多按钮模式
btns := []*dingtalk.WebhookActionCardButton{
    {
        Title:     "查看需求",
        ActionURL: "https://www.example.com/requirements",
    },
    {
        Title:     "查看设计",
        ActionURL: "https://www.example.com/design",
    },
}

err := client.SendWebhookActionCardMessageV2(
    ctx,
    webhookUrl,
    "项目进度报告",
    text,
    btns,
    "1", // 按钮横向排列
)

// 使用请求对象（推荐）
req := &dingtalk.SendActionCardRequest{
    Webhook:        webhookUrl,
    Title:          "版本更新通知",
    Text:           text,
    SingleTitle:    "立即体验",
    SingleURL:      "https://www.example.com",
    BtnOrientation: "0",
}
err := client.SendWebhookActionCardMessageV3(ctx, req)

8. 发送 FeedCard 消息

FeedCard 消息可以展示多条链接信息，每条信息包含标题、链接和图片。

// 基本用法
links := []*dingtalk.WebhookFeedCardLink{
    {
        Title:      "技术博客：Go语言最佳实践",
        MessageURL: "https://www.example.com/blog/go",
        PicURL:     "https://example.com/image1.png",
    },
    {
        Title:      "新闻：Go 1.21 正式发布",
        MessageURL: "https://www.example.com/news/go-1.21",
        PicURL:     "https://example.com/image2.png",
    },
}

err := client.SendWebhookFeedCardMessage(ctx, webhookUrl, links)

// 使用请求对象（推荐）
req := &dingtalk.SendFeedCardRequest{
    Webhook: webhookUrl,
    Links:   links,
}
err := client.SendWebhookFeedCardMessageV2(ctx, req)

消息类型说明

文本消息

• 支持纯文本内容
• 支持 @指定用户或 @所有人

Markdown 消息

• 支持标准 Markdown 语法
• 支持代码块（json, go, python 等）
• 支持 @指定用户或 @所有人
• 需要提供标题和内容

链接消息

• 支持标题、描述、跳转链接
• 可选图片展示

ActionCard 消息

• 支持 Markdown 格式内容
• 支持单按钮模式：一个按钮，点击跳转到指定链接
• 支持多按钮模式：多个按钮，每个按钮可跳转不同链接
• 按钮可选择竖直排列或横向排列
• 适用于通知、审批、选择等场景

FeedCard 消息

• 支持展示多条链接信息
• 每条信息包含标题、链接和图片
• 适用于新闻聚合、文章推荐等场景
• 用户点击可跳转到对应链接

错误处理

所有发送方法都会返回 error，建议进行错误处理：

err := client.SendWebhookTextMessage(ctx, webhookUrl, "测试消息")
if err != nil {
    log.Printf("发送消息失败: %v", err)
    return
}
log.Println("发送消息成功")

获取 Webhook 地址

1. 在钉钉群中添加自定义机器人
2. 选择"自定义"机器人类型
3. 配置安全设置（关键词、加签或IP地址）
4. 复制生成的 Webhook 地址

注意事项

1. 安全设置：钉钉机器人需要配置安全设置，支持三种方式：
   • 加签（推荐）：使用 GenerateSignedURL 方法生成带签名的URL
   • 自定义关键词：消息内容必须包含设置的关键词
   • IP地址：仅允许指定IP地址访问
2. 频率限制：钉钉机器人有频率限制，每个机器人每分钟最多发送20条消息
3. 内容长度：建议单条消息内容不要过长，避免显示不完整
4. @功能：使用@功能时，需要提供正确的手机号或用户ID
5. 签名有效期：使用加签方式时，签名有效期为1小时，超时需要重新生成

测试

运行测试前，请先在 sendmsg_test.go 中配置实际的 Webhook 地址：

const testWebhookUrl = "YOUR_DINGTALK_WEBHOOK_URL"

然后运行测试：

# 运行所有测试
go test -v

# 运行指定测试
go test -v -run TestClient_SendWebhookTextMessage

依赖

• gitee.com/hexug/go-reqx/rest - HTTP 客户端
• gitee.com/hexug/go-tools/logger - 日志库

参考文档

• 钉钉自定义机器人官方文档

License

MIT License