跳转到主要内容
当用户@群机器人或与机器人发送单聊消息时，钉钉会通过机器人开发者的HTTPS服务地址，把消息内容发送出去，本文介绍了机器人的接收消息协议。

​
HTTP header参数

{
  "Content-Type": "application/json; charset=utf-8",
  "timestamp": "1577262236757",
  "sign":"xxxxxxxxxx"
}
参数说明
timestamp消息发送的时间戳，单位是毫秒。
sign签名值。
开发者需对header中的timestamp和sign进行验证，以判断是否是来自钉钉的合法请求，避免其他仿冒钉钉调用开发者的HTTPS服务传送数据，具体验证逻辑如下：
  • timestamp 与系统当前时间戳如果相差1小时以上，则认为是非法的请求。
  • sign 与开发者自己计算的结果不一致，则认为是非法的请求。
必须当timestamp和sign同时验证通过，才能认为是来自钉钉的合法请求。

​
sign的计算方法

header中的timestamp + “\n” + 机器人的appSecret当做签名字符串，使用HmacSHA256算法计算签名，然后进行Base64 encode，得到最终的签名值。 签名计算代码示例（Java） 
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class Test {
    public static void main(String[] args) throws Exception {
        Long timestamp = 1577262236757L;
        String appSecret = "this is a secret";
        String stringToSign = timestamp + "\n" + appSecret;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
        String sign = new String(Base64.encodeBase64(signData));
        System.out.println(sign);
    }
}

​
HTTP Body

{
    "conversationId": "xxx",
    "atUsers": [
        {
            "dingtalkId": "xxx",
            "staffId":"xxx",
            "unionId":"edxxx34"
        }
    ],
    "chatbotCorpId": "dinge8a565xxxx",
    "chatbotUserId": "$:LWCP_v1:$Cxxxxx",
    "msgId": "msg0xxxxx",
    "senderNick": "杨xx",
    "isAdmin": true,
    "senderStaffId": "user123",
    "sessionWebhookExpiredTime": 1613635652738,
    "createAt": 1613630252678,
    "senderCorpId": "dinge8a565xxxx",
    "conversationType": "2",
    "senderId": "$:LWCP_v1:$Ff09GIxxxxx",
    "conversationTitle": "机器人测试-TEST",
    "isInAtList": true,
    "sessionWebhook": "https://oapi.dingtalk.io/robot/sendBySession?session=xxxxx",
    "text": {
        "content": " 你好"
    },
    "msgtype": "text"
}

​
参数说明

参数是否必填类型说明
msgtype是String消息类型。
content是String消息文本。
msgId是String加密的消息ID。
createAt是String消息的时间戳，单位毫秒。
conversationType是String1：单聊 2：群聊
conversationId是String会话ID。
conversationTitle否String群聊时才有的会话标题。
senderId是String加密的发送者ID。 说明 使用senderStaffId，作为发送者userid值。
senderNick是String发送者昵称。
senderCorpId否String企业内部群有的发送者当前群的企业corpId。
sessionWebhook是String当前会话的Webhook地址。
sessionWebhookExpiredTime是Long当前会话的Webhook地址过期时间。
isAdmin否boolean是否为管理员。 说明 机器人发布上线后生效。
chatbotCorpId否String加密的机器人所在的企业corpId。
isInAtList否boolean是否在@列表中。
senderStaffId否String企业内部群中@该机器人的成员userid。 说明 该字段在机器人发布线上版本后，才会返回。
senderUnionId否String发送人的unionid。
chatbotUserId是String加密的机器人ID。
atUsers否Array被@人的信息。 - dingtalkId：加密的被@用户的id。 - staffId：被@用户的userId，外部群中的外部用户此字段为空。 - unionId：被@的用户unionid。

​
支持接收的消息类型

机器人目前支持接收文本、语音、图片、文件、视频、富文本类型消息，下面表格是机器人接收各种消息类型的字段解释。除消息类型和消息体字段不同之外，其余参数字段与上面表格相同。

​
重要

  • 群聊会话中：群成员@机器人，机器人不支持接收语音、文件、视频类型。
  • 人与人的会话中：机器人不支持接收语音、文件、视频类型。
  • 人与机器人的会话中：机器人支持接收语音、文件、视频类型。

​
文本消息

{
  "msgtype": "text",
  "text": {
    "content": "你好"
  }
}

​
参数说明：

参数类型说明
msgtypeString消息类型： - text：文本消息
contentString文本消息内容。

​
语音消息

{
  "msgtype": "audio",
  "content": {
    "duration": 4000,
    "downloadCode": "mIofN681YE3f/+m+Nn***********geqPd7xpJF/9NbOAORDnadz0WbSwWTiYvByBeYDjbg2ecUdno/RGtZ/sqzdvoh00EWw1U6xNqLC3Bk51U+i",
    "recognition": "钉钉，让进步发生"
  }
}

​
参数说明：

参数类型说明
msgtypeString消息类型： - audio：语音消息
downloadCodeString语音文件的下载码，用于换取下载语音的二进制文件，调用服务端API-下载机器人接收消息的文件内容接口，获取临时下载链接。
recognitionString语音识别后的文本。
durationLong语音的时长，单位是毫秒。

​
图片消息

{
  "msgtype": "picture",
  "content": {
    "downloadCode": "mIofN681YE3f/+m+**********8rs4RGdQAwyVs3B75N7boKf8ep0FBB122u9YY/novFAM9BQrirm4/+avZaCV+6nnZ0Zk="
  }
}

​
参数说明：

参数类型说明
msgtypeString消息类型： - picture：图片消息
downloadCodeString图片文件的下载码，用于换取下载图片的二进制文件，调用服务端API-下载机器人接收消息的文件内容接口，获取临时下载链接。

​
视频消息

{
  "msgtype": "video",
  "content": {
    "duration": 4000,
    "downloadCode": "mIofN681YE3f/****************OAORDnadz0WbSwWTiYvByBeYDjbg2ecUdno/RGtZ/sqzdvoh00EWw1U6xNqLC3Bk51U+i",
    "videoType": "mp4"
  }
}

​
参数说明：

参数类型说明
msgtypeString消息类型： - video：视频消息
downloadCodeString视频文件的下载码，用于换取下载视频的二进制文件，调用服务端API-下载机器人接收消息的文件内容接口，获取临时下载链接。
videoTypeString视频文件类型。
durationLong视频的时长，单位是毫秒。

​
文件消息

{
  "msgtype": "file",
  "content": {
    "downloadCode": "mIofN681YE3f*************pJF/9NbOAORDnadz0WbSwWTiYvByBeYDjbg2ecUdno/RGtZ/sqzdvoh00EWw1U6xNqLC3Bk51U+i",
    "fileName": "钉钉让进步发生.pdf"
  }
}

​
参数说明：

参数类型说明
msgtypeString消息类型： - video：文件消息
downloadCodeString文件的下载码，用于换取下载文件的二进制文件，调用服务端API-下载机器人接收消息的文件内容接口，获取临时下载链接。
fileNameString文件名。

​
富文本消息

{
  "msgtype": "richText",
  "content": {
    "richText": [
      {
        "text": "你好"
      },
      {
        "downloadCode": "mIofN681YE3f*************JkVBG2vhj4Q9TsmsNCHy0Phdd2tn/t6XxjaB6U8oEst1JVnFR2QRaLqsGyuWPhEvzhIDEpfQYEvexbwdKCCpMOVnYYbn1aMT/n3JFgb4i64X3TFXxXCdaH1+NLRM/B6kGWxJPR/egKS8syvGzaZpzVI+hHQbCjLOO/FYLor2Q==",
        "type": "picture"
      }
    ]
  }
}

​
参数说明：

名称类型是否必填描述
msgtypeString是消息类型： - richText：富文本
contentObject是消息内容。
richTextArray是富文本列表。 说明 消息列表中可以包含： - **text：**文本消息 - picture：图片消息

​
HTTP响应格式

开发者可以根据自己的业务需要，选择回复一段消息，目前支持text、markdown、整体跳转actionCard类型、独立跳转actionCard类型、feedCard这5种消息类型。