消息发送与接收类型

本文介绍了通过机器人发送消息的类型与数据格式，并详细介绍了机器人接收消息的数据格式。

机器人发送消息

消息类型

发送机器人消息的方式有2种，通过接口发送机器人消息和通过Webhook发送机器人消息。不同的方式，支持的消息类型和数据格式不同。

推荐使用接口方式发送消息。

消息类型	接口方式发送机器人消息	Webhook 方式发送机器人消息
Text文本类型	✅	✅
Markdown类型	✅	✅
图片Image类型	✅	❌
ActionCard类型	✅	✅
FeedCard类型	❌	✅
Link链接消息	✅	✅
Audio语音类型	✅	❌
File文件类型	✅	❌
Video视频类型	✅	❌

方式一：接口方式

重要

人与机器人会话中机器人消息：支持图片、语音、文件收发能力。
群聊会话中机器人消息：图片、语音、视频、文件发送能力**，但群聊中用户无法@机器人发送语音、视频、文件给机器人**。

适用接口

数据格式

消息模板Key：消息模板Key是开发者发送消息时需要用到的一个唯一标识。它可以在编写程序代码时，能快速地指向一个事先设定好的消息模板。
消息模板参数：用于在消息模板中替换预定义占位符的实际数据。例如，当你有一个sampleText消息模板Key时，此时你需要定义content字段的值。
示例：提供了企业内部应用机器人在群内发送文本类型的 HTTP 示例代码：
- 消息模板Key： "msgKey" : "sampleText"
- 消息模板参数： "msgParam" : "{\"content\":\"钉钉，让进步发生\"}"

详情参考机器人发送群聊消息。

POST /v1.0/robot/groupMessages/send HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:<your access token>
Content-Type:application/json

{
  "msgParam" : "{\"content\":\"钉钉，让进步发生\"}",
  "msgKey" : "sampleText",
  "openConversationId" : "cid6KeBBLov********",
  "robotCode" : "dingue4kfzdxbyn*******"
}

消息类型	消息模板Key	消息模板参数	说明
文本类型	sampleText	`{ "content": "xxxx" }`
Markdown类型	sampleMarkdown	`{ "title": "xxxx", "text": "xxxx" }`
图片类型	sampleImageMsg	`{ "photoURL": "xxxx" }`	说明 photoURL可填写图片的完整URL路径，也可填写图片的mediaId。mediaId可通过上传媒体文件接口，获取`media_id`参数值。
链接类型	sampleLink	`{ "text": "消息内容测试", "title": "sampleLink消息测试", "picUrl": "@lADOADmaWMzazQKA", "messageUrl": "http://dingtalk.io" }`	链接消息。
ActionCard类型	sampleActionCard	`{ "title": "测试标题", "text": "内容测试", "singleTitle": "查看详情", "singleURL": "https://open.dingtalk.com" }`	卡片消息：一个按钮。一个按钮
sampleActionCard2	`{ "title": "消息标题测试", "text": "消息正文测试", "actionTitle1": "一个按钮", "actionURL1": "https://www.taobao.com", "actionTitle2": "两个按钮", "actionURL2": "https://www.tmall.com" }`	卡片消息：竖向二个按钮。两个按钮竖直按钮
sampleActionCard3	`{ "title": "消息标题测试", "text": "消息内容测试", "actionTitle1": "第一个按钮的文本", "actionURL1": "第一个按钮触发的url", "actionTitle2": "第二个按钮的文本", "actionURL2": "第二个按钮触发的url", "actionTitle3": "第三个按钮的文本", "actionURL3": "第三个按钮触发的url" }`	卡片消息：竖向三个按钮。
sampleActionCard4	`{ "title":"消息标题测试", "text":"消息内容测试", "actionTitle1":"第一个按钮的文本", "actionURL1":"第一个按钮触发的url", "actionTitle2":"第二个按钮的文本", "actionURL2":"第二个按钮触发的url", "actionTitle3":"第三个按钮的文本", "actionURL3":"第三个按钮触发的url", "actionTitle4":"第四个按钮的文本", "actionURL4":"第四个按钮触发的url" }`	卡片消息：竖向四个按钮。
sampleActionCard5	{ "title":"消息标题测试", "text":"消息内容测试", "actionTitle1":"第一个按钮的文本", "actionURL1":"第一个按钮触发的url", "actionTitle2":"第二个按钮的文本", "actionURL2":"第二个按钮触发的url", "actionTitle3":"第三个按钮的文本", "actionURL3":"第三个按钮触发的url", "actionTitle4":"第四个按钮的文本", "actionURL4":"第四个按钮触发的url", "actionTitle5":"第五个按钮的文本", "actionURL5":"第五个按钮触发的url" }	卡片消息：竖向五个按钮。
sampleActionCard6	`{ "title": "xxxx", "text": "xxxx", "buttonTitle1":"xxxxx", "buttonUrl1":"xxxxx", "buttonTitle2":"xxxxx", "buttonUrl2":"xxxxx" }`	卡片消息：横向二个按钮。横向按钮
语音类型	sampleAudio	`{ "mediaId": "@IR_P********nFkfhsisbf4A", "duration":"xxxxx" }`	语音消息： - mediaId：通过上传媒体文件接口，获取`media_id`参数值。说明支持ogg、amr格式。 - duration：语音消息时长，单位毫秒。 image
文件类型	sampleFile	`{ "mediaId":"@lAz*********shRs5m2pRL", "fileName":"表格.xlsx", "fileType":"xlsx" }`	文件消息： - mediaId：通过上传媒体文件接口，获取`media_id`参数值。 - fileName：文件名称。 - fileType：文件类型。说明文件类型，支持xlsx、pdf、zip、rar、doc、docx格式。 image
视频类型	sampleVideo	`{ "duration":"999", "videoMediaId":"$iQEL********AXNSs6QPPAAABhKN2L3EEzTcTB84BFM7iCAAJomlt", "videoType":"mp4", "picMediaId":"$igE********tAFzQUABtoAIYQBpAtR3SICqrQ7ZX0nEJzAKxUDzwAAAYSjdi2cBM02vwcACAAJomltCgQ" }`	视频消息： - duration：语音消息时长，单位秒。 - videoMediaId：通过上传媒体文件接口，获取`media_id`参数值。 - videoType：视频类型，支持mp4格式。 - picMediaId：视频封面图，通过上传媒体文件接口，获取`media_id`参数值。 - height：视频展示高度，单位px。 - width：视频展示宽度，单位px。

Markdown支持的语法

对于消息类型 sampleMarkdown 的markdown语法的补充说明。

标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
 
引用
> A man who stands for nothing will fall for anything.
 
文字加粗、斜体
**bold**
*italic*
 
链接
[this is a link](http://name.com)
 
图片
![](http://name.com/pic.jpg)
 
无序列表
- item1
- item2
 
有序列表
1. item1
2. item2

换行
 \n (建议\n前后分别加2个空格)

方式二：Webhook方式

webhook方式只支持在群聊会话。

Webhook发送消息的实现方式，请参考机器人回复/发送消息和创建自定义机器人。

文本text类型

{
    "at": {
        "atMobiles": [
            "180xxxxxx"
        ],
        "atUserIds": [
            "user123"
        ],
        "isAtAll": false
    },
    "text": {
        "content": "我就是我, @180xxxxxx 是不一样的烟火"
    },
    "msgtype": "text"
}

参数	是否必填	类型	说明
msgtype	是	String	text。
content	是	String	消息文本。
atMobiles	否	Array	被@人的手机号。说明在content里添加@人的手机号，且只有在群内的成员才可被@，非群内成员手机号会被脱敏。
atUserIds	否	Array	被@人的用户userid。说明在content里添加@人的userId。
isAtAll	否	Boolean	@所有人是true，否则为false。

链接Link类型

该类型不支持@人。

{
    "msgtype": "link", 
    "link": {
        "text": "这个即将发布的新版本，创始人xx称它为红树林。而在此之前，每当面临重大升级，产品经理们都会取一个应景的代号，这一次，为什么是红树林", 
        "title": "时代的火车向前开", 
        "picUrl": "https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png", 
        "messageUrl": "https://open.dingtalk.com/document/"
    }
}

参数	参数类型	是否必填	说明
msgtype	String	是	消息类型，此时固定为：link。
title	String	是	消息标题。
text	String	是	消息内容，如果太长只会部分展示。
messageUrl	String	是	点击消息跳转的URL，打开方式如下： - 移动端，在钉钉客户端内打开 - PC端 - 默认侧边栏打开 - 希望在外部浏览器打开，参考消息链接说明。
picUrl	String	否	图片URL。

Markdown类型

{
     "msgtype": "markdown",
     "markdown": {
         "title":"杭州天气",
         "text": "#### 杭州天气 @150XXXXXXXX \n> 9度，西北风1级，空气良89，相对温度73%\n> ![screenshot](https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png)\n> ###### 10点20分发布 [天气](https://www.dingalk.com) \n"
     },
      "at": {
          "atMobiles": [
              "150XXXXXXXX"
          ],
          "atUserIds": [
              "user123"
          ],
          "isAtAll": false
      }
 }

参数	是否必填	类型	说明
msgtype	是	String	消息类型，此时固定为：markdown。
title	是	String	首屏会话透出的展示内容。
text	是	String	Markdown格式的消息内容。
atMobiles	否	Array	被@人的手机号。说明在text内容里要有@人的手机号，只有在群内的成员才可被@，非群内成员手机号会被脱敏。
atUserIds	否	Array	被@人的用户userid。说明在 text 中添加@人的userId。
isAtAll	否	Boolean	@所有人是true，否则为false。

目前只支持Markdown语法的子集，支持的元素如下：

标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
 
引用
> A man who stands for nothing will fall for anything.
 
文字加粗、斜体
**bold**
*italic*
 
链接
[this is a link](https://www.dingtalk.io/)
 
图片
![](http://name.com/pic.jpg)
 
无序列表
- item1
- item2
 
有序列表
1. item1
2. item2

ActionCard类型

整体跳转ActionCard类型

{
    "msgtype": "actionCard",
    "actionCard": {
        "title": "打造一间咖啡厅", 
        "text": "![screenshot](https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png) \n #### 乔布斯 20 年前想打造的苹果咖啡厅 \n\n Apple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划",
        "singleTitle" : "阅读全文",
        "btnOrientation": "0", 
        "singleURL" : "https://www.dingtalk.io/"
    }
}

参数	是否必填	类型	说明
msgtype	是	String	消息类型，此时固定为：actionCard。
title	是	String	首屏会话透出的展示内容。
text	是	String	markdown格式的消息。说明如果需要实现 @ 功能，在 text 内容中添加 @ 用户的 userId。例如：@manager7675
singleTitle	是	String	单个按钮的标题。
singleURL	是	String	点击消息跳转的URL，打开方式如下： - 移动端，在钉钉客户端内打开 - PC端 - 默认侧边栏打开 - 希望在外部浏览器打开，参考消息链接说明。
btnOrientation	否	String	按钮排列方式： - 0：按钮竖直排列 - 1：按钮横向排列

独立跳转ActionCard类型

{
    "msgtype": "actionCard",
    "actionCard": {
        "title": "乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身", 
        "text": "![screenshot](https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png) \n\n #### 乔布斯 20 年前想打造的苹果咖啡厅 \n\n Apple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划", 
        "btnOrientation": "0", 
        "btns": [
            {
                "title": "内容不错", 
                "actionURL": "https://www.dingtalk.io/"
            }, 
            {
                "title": "不感兴趣", 
                "actionURL": "https://www.dingtalk.io/"
            }
        ]
    }
}

参数	是否必填	类型	说明
msgtype	是	String	actionCard。
title	是	String	首屏会话透出的展示内容。
text	是	String	markdown格式的消息内容。说明如果需要实现 @ 功能，在 text 内容中添加 @ 用户的 userId。例如：@manager7675
btns	是	Array	按钮。
title	是	String	按钮标题。
actionURL	是	String	击按钮触发的URL，打开方式如下： - 移动端，在钉钉客户端内打开 - PC端 - 默认侧边栏打开 - 希望在外部浏览器打开，参考消息链接说明。
btnOrientation	否	String	按钮排列顺序。 0：按钮竖直排列 1：按钮横向排列

FeedCard类型

该类型不支持@人。

{
    "msgtype": "feedCard",
    "feedCard": {
        "links": [
            {
                "title": "时代的火车向前开1", 
                "messageURL": "https://www.dingtalk.io/", 
                "picURL": "https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png"
            },
            {
                "title": "时代的火车向前开2", 
                "messageURL": "https://www.dingtalk.io/", 
                "picURL": "https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png"
            }
        ]
    }
}

参数	是否必填	类型	说明
msgtype	是	String	feedCard。
title	是	String	单条信息文本。
messageURL	是	String	点击单条信息到跳转链接，详情参考消息链接说明。
picURL	是	String	单条信息后面图片的URL。

当不想回复消息到群里时，回复格式如下：

{
    "msgtype": "empty"
}

机器人接收消息

当用户@群机器人或与机器人发送单聊消息时，钉钉会把机器人接收到的消息发送到开发者设置的机器人回调服务。

消息体

本示例以 text 文本类型为例：如果你使用 HTTP 回调的方式，使用 POST 请求接收钉钉推送的消息。

{
  "senderPlatform": "Mac",
  "conversationId": "cid6EUxxxxsg==",
  "atUsers": [
    {
      "dingtalkId": "xxx",
      "staffId":"xxx",
      "unionId":"edxxx34"
    }
  ],
  "chatbotCorpId": "ding9733d095*******6cb783455b",
  "chatbotUserId": "$:LWCP_xxxxr5",
  "msgId": "msgrK2xxxxU+riw==",
  "senderNick": "小钉",
  "isAdmin": true,
  "senderStaffId": "0147xxxx8602",
  "sessionWebhookExpiredTime": 1708332604316,
  "createAt": 1708327204136,
  "senderCorpId": "ding9733d095*******6cb783455b",
  "conversationType": "2",
  "senderId": "$:LWCP_v1xxxxBv1MhAv9",
  "conversationTitle": "测试群",
  "isInAtList": true,
  "sessionWebhook": "https://oapi.dingtalk.io/robot/sendBySession?session=66d7c695a9xxxxdeb885",
  "text": {
    "content": " text"
  },
  "robotCode": "dingoxxxxdm3k",
  "msgtype": "text"
}

参数	类型	说明
senderPlatform	String	消息发送平台。
conversationId	String	会话ID。
atUsers	Array of Object	被@人的信息。 - dingtalkId：加密的被@用户的id。 - staffId：被@用户的userId，外部群中的外部用户此字段为空。 - unionId：被@的用户unionid。
chatbotCorpId	String	加密的机器人所在的企业corpId。
chatbotUserId	String	加密的机器人ID。
msgId	String	加密的消息ID。
senderNick	String	发送者昵称。
isAdmin	Boolean	是否为管理员： - true：是 - false：否机器人发布上线后生效，否则不返回。
senderStaffId	String	企业内部群中@该机器人的成员 userId。如果发送人非机器人所在企业成员，则此字段为空（比如外部群里外部成员@机器人的情况）。机器人发布上线后生效。否则不会返回。
senderUnionId	String	发送人的unionid。
sessionWebhookExpiredTime	Long	当前会话的Webhook地址过期时间。
createAt	String	消息的时间戳，单位毫秒。
senderCorpId	String	企业内部群的发送者当前群的企业corpId。
conversationType	String	会话类型： - 1：单聊 - 2：群聊
senderId	String	加密的发送者ID。
conversationTitle	String	群聊时才有的会话标题。
isInAtList	Boolean	是否在@列表中。
sessionWebhook	String	当前会话的Webhook地址。
text	Object	消息文本： - content：机器人接收的消息内容。该字段仅在消息类型为 text 存在。
msgtype	String	消息类型： - text：文本消息 - richText：富文本消息 - picture：图片消息 - audio：语音消息 - video：视频消息 - file：文件消息消息类型的具体格式参看下方消息类型。
robotCode	String	机器人编码。自定义机器人无 robotCode。

消息类型

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

文本消息

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

参数	类型	说明
msgtype	String	消息类型： - text：文本消息
text	Object	消息文本： - content：机器人接收的消息内容。

富文本消息

{
  "msgtype": "richText",
  "content": {
    "richText": [
      {
        "text": "你好"
      },
      {
        "downloadCode": "mIofN681YE3f*************JkVBG2vhj4Q9、d2tn/t6XxjaB6UxxxxOVnYYbn1aMT/n3JFgb4i64X3TFxxxxGWxJPR/egKS8syvGzxxxxOO/FYLor2Q==",
        "type": "picture"
      }
    ]
  }
}

名称	类型	描述
msgtype	String	消息类型： - richText：富文本
content	Object	消息内容。
richText	Array of Object	富文本列表。说明消息列表中可以包含： - text：文本消息 - picture：图片消息图片文件的下载码downloadCode，可通过调用服务端API-下载机器人接收消息的文件内容接口获取临时下载链接。

图片消息

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

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

语音消息

群聊会话中，群成员 @机器人时，机器人不支持接收语音消息。

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

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

视频消息

群聊会话中，群成员 @机器人时，机器人不支持接收视频消息。

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

参数	类型	说明
msgtype	String	消息类型： - video：视频消息
downloadCode	String	视频文件的下载码，用于换取下载视频的二进制文件，可通过调用服务端API-下载机器人接收消息的文件内容接口获取临时下载链接。
videoType	String	视频文件类型。
duration	Long	视频的时长，单位是毫秒。

文件消息

群聊会话中，群成员 @机器人时，机器人不支持接收文件消息。

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

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

参数	说明
timestamp	消息发送的时间戳，单位是毫秒。
sign	签名值。

配置项	说明
timestamp	当前时间的时间戳，单位毫秒
appSecret	应用的 Client Secret，详情参考Client Secret。

错误码

当机器人 Webhook 和 Stream 用量超量后，则会出现以下内容：

错误表现

群聊会话

单聊会话

错误说明

错误码（errorCode）	错误信息（errorMessage）	说明	解决方案
20001	受调用量超量影响，当前我的消息服务已经暂停。请联系你所在的组织管理员并予以处理接收消息中，新增 errorMessage 字段，用于展示错误信息。	- 接收消息中无 text 和 content 字段内容 - 登录开发者后台即可查看调用量。 image	需要升级钉钉专业版或购买增购包，详情参看企业增购包购买说明。

API 调用指南

认证与授权

通讯录管理

日程

音视频

AI 表格

文档/文件

即时通信

机器人发送消息

消息类型

方式一：接口方式

重要

适用接口

数据格式

Markdown支持的语法

方式二：Webhook方式

文本text类型

链接Link类型

Markdown类型

ActionCard类型

FeedCard类型

机器人接收消息

消息体

消息类型

文本消息

富文本消息

图片消息

语音消息

视频消息

文件消息

相关内容

错误码

错误表现

群聊会话

单聊会话

错误说明

相关文档

​机器人发送消息

​消息类型

​方式一：接口方式

​重要

​适用接口

​数据格式

​Markdown支持的语法

​方式二：Webhook方式

​文本text类型

​链接Link类型

​Markdown类型

​ActionCard类型

​FeedCard类型

​机器人接收消息

​消息体

​消息类型

​文本消息

​富文本消息

​图片消息

​语音消息

​视频消息

​文件消息

​相关内容

​错误码

​错误表现

群聊会话

单聊会话

​错误说明

​相关文档

机器人发送消息

消息类型

方式一：接口方式

重要

适用接口

数据格式

Markdown支持的语法

方式二：Webhook方式

文本text类型

链接Link类型

Markdown类型

ActionCard类型

FeedCard类型

机器人接收消息

消息体

消息类型

文本消息

富文本消息

图片消息

语音消息

视频消息

文件消息

相关内容

错误码

错误表现

错误说明

相关文档