从0到1接入钉钉消息通知

前段时间给项目接入监控告警，消息通知渠道选了钉钉。预算的原因内部办公刚从飞书转回钉钉，飞书消息通知之前就有一套了，测试钉钉从应用授权到消息测试花了不少时间。这里记录下从钉钉开放平台权限申请到消息接收全流程，给后面有同样需求的人少踩坑。

申请开发者权限

让组织管理员在OA管理后台给你分配权限

或者自己新建一个测试主体，你就是管理员。因为没有组织架构，后面部门群组都要新建。
参考：https://open.dingtalk.com/document/dashboard/become-a-dingtalk-developer

创建应用

登录后台创建企业内部应用


建完你可以拿到AgentId、AppKey和AppSecret，后面对接开放平台接口的时候都要用到。

获取授权

拿到accessToken。
https://api.dingtalk.com/v1.0/oauth2/accessToken
入参

{
	"appKey":"xx",
	"appSecret":"xxx"
}

返回

{
	"expireIn":7200,
	"accessToken":"xxx"
}

接下来创建组织架构

创建部门

比如创建一级部门，技术部。
https://oapi.dingtalk.com/topapi/v2/department/create?access_token=xxx

{
	"name":"技术部",
	"parent_id":1
}

会返回部门ID

{
	"errcode":0,
	"result":{
		"dept_id":xxx
	},
	"errmsg":"ok",
	"request_id":"16mgjgpq1o4az"
}

用户信息创建

往架构里面添加人，需要绑定手机号。
https://oapi.dingtalk.com/topapi/v2/user/create?access_token=xxx

{
	"name":"Mary",
	"mobile":"168xxx",
	"dept_id_list":"xxx"
}

返回用户ID

{
	"errcode":0,
	"result":{
		"unionId":"xxx",
		"userid":"xxx"
	},
	"errmsg":"ok",
	"request_id":"16m7cylmugy2d"
}

钉钉发送消息有两种方式，一种是工作通知，后面接收人列表如果要加入，就需要单独把对应的用户id加进来。
另一种是发送群聊消息，在群聊里面加个机器人虚拟用户，后面如果需要添加接收人，只需要把对应的人拉到群里就行了，消息是直接发群里的。

发送工作通知

https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=xx
比如发送一句文本通知

{
	"msg":{
		"msgtype":"text",
		"oa":{
			"body":{
				"content":"Linda监控告警消息测试"
			}
		},
		"text":{
			"content":"Linda监控告警消息测试"
		}
	},
	"to_all_user":false,
	"agent_id":xx,
	"userid_list":"xx"
}

agent_id是前面创建应用的时候，在应用详情的应用凭证AgentId，userid_list是目标用户ID列表。
发送完会返回任务ID，如果消息没触达，可以用于回溯排查问题。

{
	"errcode":0,
	"errmsg":"ok",
	"task_id":xx,
	"request_id":"16m2lh8dy44el"
}

接收到是这样的

还可以创建更复杂一点的工作通知

{
	"msg":{
		"msgtype":"oa",
		"oa":{
			"body":{
				"file_count":"2",
				"title":"技术度量",
				"author":"Linda",
				"content":"需求交付率(%)\t需求总工时(h)\t需求平均工时(h)\t冒烟通过率(%)\tBUG日清率(%)\tBUG完成率(%)\tBUG总工时(h)\tBUG平均工时(h)"
			},
			"head":{
				"bgcolor":"FFBBBBBB",
				"text":"季度缺陷报告"
			}
		},
		"text":{
			"content":"Linda监控告警消息测试"
		}
	},
	"to_all_user":false,
	"agent_id":xx,
	"userid_list":"xxx"
}

这里也支持Markdown格式的工作通知，但是测试的显示效果不理想，排版直接乱掉。

{
	"agent_id":xx,
	"msg":{
		"link":{
			"title":"Nacos使用手册",
			"text":"# Nacos-examples [中文](./README.md)  > 这是 Nacos java 程序样例，你可以通过 Nacos 原生SDK / Spring 操作服务和配置 ## 启动 Nacos  你可以本机启动单机模式Nacos  https://nacos.io/zh-cn/docs/deployment.html  你也可以从阿里云上购买Nacos开发版  https://help.aliyun.com/document_detail/139460.html  https://www.aliyun.com/product/aliware/mse?spm=nacos-website.topbar.0.0.0"
		},
		"markdown":{
			"title":"Nacos使用手册",
			"text":"# Nacos-examples [中文](./README.md)  > 这是 Nacos java 程序样例，你可以通过 Nacos 原生SDK / Spring 操作服务和配置 ## 启动 Nacos  你可以本机启动单机模式Nacos  https://nacos.io/zh-cn/docs/deployment.html  你也可以从阿里云上购买Nacos开发版  https://help.aliyun.com/document_detail/139460.html  https://www.aliyun.com/product/aliware/mse?spm=nacos-website.topbar.0.0.0"
		},
		"oa":{
			"body":{
				"title":"Nacos使用手册"
			},
			"head":{
				"text":"# Nacos-examples [中文](./README.md)  > 这是 Nacos java 程序样例，你可以通过 Nacos 原生SDK / Spring 操作服务和配置 ## 启动 Nacos  你可以本机启动单机模式Nacos  https://nacos.io/zh-cn/docs/deployment.html  你也可以从阿里云上购买Nacos开发版  https://help.aliyun.com/document_detail/139460.html  https://www.aliyun.com/product/aliware/mse?spm=nacos-website.topbar.0.0.0"
			}
		},
		"msgtype":"markdown",
		"action_card":{
			"title":"Nacos使用手册",
			"btn_json_list":[
				{
					"title":"Nacos使用手册"
				}
			]
		}
	},
	"userid_list":"xx"
}

获取工作通知消息的发送结果

https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult?access_token=xx

{
	"agent_id":xx,
	"task_id":xx
}

有时发完没收到消息，可能不是传参的问题，仅仅是发送频率被限制了。

{
	"errcode":41045,
	"errmsg":"超过发送全员消息的次数上限，每天最多3次",
	"request_id":"15rostv26oohc"
}

如果是发送群聊消息，需要先创建群会话。

创建群会话

https://oapi.dingtalk.com/chat/create?access_token=xx
owner指定群主，useridlist为群用户列表

{
	"owner":"xxx",
	"mentionAllAuthority":0,
	"showHistoryType":1,
	"validationType":0,
	"name":"Linda消息通知",
	"useridlist":"[\"xxx\"]",
	"searchable":1,
	"chatBannedType":0,
	"managementType":0
}

返回群ID

{
	"errcode":0,
	"chatid":"xx",
	"conversationTag":2,
	"errmsg":"ok",
	"openConversationId":"xx"
}

应用添加机器人

进入应用，在消息推送开启机器人配置，拿到RobotCode

机器人发送群聊消息

header
{
	"x-acs-dingtalk-access-token":"xx"
}
body
{
	"msgParam":"{\"content\": \"Linda monitor notify\"}",
	"msgKey":"sampleText",
	"robotCode":"xx",
	"openConversationId":"xx"
}

返回

{
	"processQueryKey":"xx"
}