从零开始打造专属钉钉机器人

官方定义如下：

群机器人是钉钉群的高级扩展功能。群机器人可以将第三方服务的信息聚合到群聊中，实现自动化的信息同步。目前，大部分机器人在添加后，还需要进行Webhook配置，才可正常使用(配置说明详见操作流程中的帮助链接)。

例如：

通过聚合GitHub，GitLab等源码管理服务，实现源码更新同步。

通过聚合Trello，JIRA等项目协调服务，实现项目信息同步。

另外，群机器人支持Webhook协议的自定义接入，支持更多可能性，例如：你可将运维报警通过自定义机器人聚合到钉钉群实现提醒功能。

实际上，通过机器人我们可以对接各类服务，比如源码提交通知，服务器告警通知，甚至是可以主动查询天气、加班点餐等服务。

目前钉钉机器人支持incoming方式，outgoing仍属于内侧阶段。官方文档可以点此查看。

incoming方式

incoming是指被动接受通知，钉钉群中添加的群机器人默认都是该模式。

添加机器人

我们添加的时候可以看到已经自带一些常见的机器人，比较推荐的是GitHub、GitLab、JIRA、Travis、Trello，当然我们这次需要选择最后的"自定义"机器人。

在机器人信息栏填写"机器人姓名"即可，需要的话也可以设置一个头像。图中"是否开启Outgoing机制"在没有开通的情况下是不可见。

点击完成就会生成hook地址，如下图：

我们会用到"Hook地址"，后面我们发送消息都需要请求到该地址。

如何发送消息

只要想Webhook地址发起POST请求，带上特定格式消息即可。

具体的接口文档可以看官方，这里不做扩展。

开源工具

在一些简单的通知场景，我们可以使用npm上面的轮子来快速实现。

outgoing方式

outgoing机器人的配置和前面基本一样，只需要额外配置POST 地址以及Token。

需要注意的是Token保存后无法再次修改，POST 地址就是钉钉机器人接受消息后调用的地址。

开通方式

钉钉上加入"钉钉机器人交流群"，群号:11733391
在 https://open-dev.dingtalk.com 首页上找到corpId
记得添加"大柚"，并把coprId私发给他。

目前每周四提交开通，预计周五会生效。

如何收取消息

当群里有人@机器人时，钉钉会通过POST方式回调我们前面设置的地址，该地址实质是接口，可以在Body中获取到消息内容。

截止撰写文章时，钉钉的outgoing机器人文档不可访问，所以会在下面介绍下。

钉钉请求格式

HTTP Header 格式如下：

 "Content-Type": "application/json; charset=utf-8" 
 "token": "6a71a455ffcfba92a66"

HTTP Body 文本消息内容：

{
     // 会话id
    "conversationId": "8Yu7H8H8890kkl7h==",
    "atUsers": [
        {
            "dingtalkId": "$:DFDS51:$R7E8dffdufdfjsdf2/oUCO/"
        }
    ],
    "chatbotUserId": "$:df3234:$sdfsdfsdfsdfd234234/oUCO/",
    "msgId": "msg4sdf35jh8jc9b51ss6/noYdzw==",
    "senderNick": "Neo",
    "isAdmin": false,
    "sessionWebhookExpiredTime": 1561711409165,
    // 消息发送的时间
    "createAt": 1561710209132,
    // 群聊消息类型还是单聊
    "conversationType": "2",
    "senderId": "$:ASDD_v1:$df8sdfj&JS*J#FF==",
    // 当类型是群聊时，这个参数有效
    "conversationTitle": "avalon",
    "isInAtList": true,
     // sessionWebhook是临时的发送消息接口
    "sessionWebhook": "https://oapi.dingtalk.com/robot/sendBySession?session=qwe",
    // 消息内容
    "text": {
        "content": "我就是我, 是不一样的烟火" 
    }, 
     // 消息类型
    "msgtype": "text",
}

HTTP 响应格式

支持返回文本、图片和markdown，actionCard，feedCard消息类型。

下面仅列出markdown格式的消息，详细的文件可以参考网友提供的PDF，提取码: 4qht 。

{
     "msgtype": "markdown", // 消息类型
     "markdown": {
         "title":"杭州天气", // 消息主题
         "text": "#### 杭州天气 @ptt6gbq @17681800905 \n" +
                 "> 9度，西北风1级，空气良89，相对温度73%\n\n" +
                 "> ![screenshot](http://image.jpg)\n"  +
                 "> ###### 10点20分发布 [天气](http://www.thinkpage.cn/) \n" // 消息体
     },
      "at": { // @的人员
          "atMobiles": [
              "17681800905"
          ], 
          "atDingtalkIds": [
              "ptt6gbq"
          ],
          "isAtAll": false
      }
 }

如果我们回复的消息需要@某人，就会配置at字段，里面atDingtalkIds需要的dingtaklId可以是我们从请求中拿到的senderId，即$:ASDD_v1:$k8DFJ837349On my way!==的形式也可以传入正常@。

另外如果出于某些原因，无法响应请求时返回消息，我们还可以通过sessionWebhook来主动发送消息。

版权声明：本文为原创文章，版权归 neo 所有。
本文链接：https://idayer.com/get-your-own-dingtalk-robot/

本作品采用知识共享署名-非商业性使用 4.0 国际许可协议进行许可。

9 条评论

r 2020年10月21日4:45 上午

为什么我添加机器人没有outgoing的功能呢

回复↓
1. neo 作者2020年11月3日8:59 下午
  
  钉钉现在outgoing改为使用企业内部机器人方式实现，可以参考文档 https://ding-doc.dingtalk.com/doc#/serverapi2/elzz1p
  
  回复↓
陈飞 2020年4月14日5:35 下午

看了半天，没琢磨明白，是要借助工具发送POST给机器人然后输出消息吗？而且需要@机器人

回复↓
1. neo 作者2020年4月14日5:41 下午
  
  有两个情况：
  1：通过api主动调用机器人，机器人会在群里发送你指定的信息。
  2：@机器人是可以和机器人交互，比如你说今天天气怎么样，机器人就会回答你天气。
  
  回复↓
unmurphy 2020年3月19日6:05 下午

你好，问一下sessionWebhook 这个发送消息的窗口有效期好像只有90分钟，有什么办法可以持久发送消息么？

回复↓
1. neo 作者2020年3月19日6:09 下午
  
  首先可以直接把内容放到请求响应中，另外可以借助`Webhook`地址，直接请求到该地址。
  
  回复↓
  1. unmurphy 2020年3月20日9:45 上午
    
    你好，谢谢回复！
    1: 我们现在的场景是机器人+h5应用场景，h5应用会有一段审批流程，审批流程完成之后会往之前的机器人群发送消息，但是在此之前如果没有人@机器人的话，之前的sessionWebhook就会过期
    2: 我们也考虑过直接使用Webhook地址，但是这个机器人可能会被很多钉钉群添加，作为后端我没有办法知道哪些群被添加了机器人，好像钉钉也未能提供对应API
23323 2019年9月17日6:01 下午

请问一下。一定要@机器人才能收到消息吗

回复↓
1. neo 作者2019年9月20日5:12 上午
  
  目前看公开的机器人用法中是不支持机器人静默获取所有消息的。
  
  回复↓