文档中心 > 群机器人

获取自定义机器人webhook

  • 在机器人管理页面选择“自定义”机器人,输入机器人名字并选择要发送消息的群。如果需要的话,可以为机器人设置一个头像。点击“完成添加”。

image

image

  • 点击“复制”按钮,即可获得这个机器人对应的Webhook地址,其格式如下
https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx

使用自定义机器人

  • 获取到Webhook地址后,用户可以使用任何方式向这个地址发起HTTP POST 请求,即可实现给该群组发送消息。注意,发起POST请求时,必须将字符集编码设置成UTF-8。

  • 当前自定义机器人支持文本(text)、连接(link)、markdown(markdown)三种消息类型,大家可以根据自己的使用场景选择合适的消息类型,达到最好的展示样式。具体的消息类型参考下一节内容。

  • 自定义机器人发送消息时,可以通过手机号码指定“被@人列表”。在“被@人列表”里面的人员,在收到该消息时,会有@消息提醒(免打扰会话仍然通知提醒,首屏出现“有人@你”)

消息类型及数据格式

text类型

{
    "msgtype": "text", 
    "text": {
        "content": "我就是我, 是不一样的烟火"
    }, 
    "at": {
        "atMobiles": [
            "156xxxx8827", 
            "189xxxx8325"
        ], 
        "isAtAll": false
    }
}
参数 参数类型 必须 说明
msgtype String 消息类型,此时固定为:text
content String 消息内容
atMobiles Array 被@人的手机号
isAtAll bool @所有人时:true,否则为:false

文本消息

link类型

{
    "msgtype": "link", 
    "link": {
        "text": "这个即将发布的新版本,创始人陈航(花名“无招”)称它为“红树林”。
而在此之前,每当面临重大升级,产品经理们都会取一个应景的代号,这一次,为什么是“红树林”?", 
        "title": "时代的火车向前开", 
        "picUrl": "", 
        "messageUrl": "https://mp.weixin.qq.com/s?__biz=MzA4NjMwMTA2Ng==&mid=2650316842&idx=1&sn=60da3ea2b29f1dcc43a7c8e4a7c97a16&scene=2&srcid=09189AnRJEdIiWVaKltFzNTw&from=timeline&isappinstalled=0&key=&ascene=2&uin=&devicetype=android-23&version=26031933&nettype=WIFI"
    }
}
参数 参数类型 必须 说明
msgtype String 消息类型,此时固定为:link
title String 消息标题
text String 消息内容。如果太长只会部分展示
messageUrl String 点击消息跳转的URL
picUrl String 图片URL

link消息

markdown类型

{
     "msgtype": "markdown",
     "markdown": {
         "title":"杭州天气",
         "text": "#### 杭州天气 @156xxxx8827\n" +
                 "> 9度,西北风1级,空气良89,相对温度73%\n\n" +
                 "> ![screenshot](http://image.jpg)\n"  +
                 "> ###### 10点20分发布 [天气](http://www.thinkpage.cn/) \n"
     },
    "at": {
        "atMobiles": [
            "156xxxx8827", 
            "189xxxx8325"
        ], 
        "isAtAll": false
    }
 }
参数 必选 类型 说明
msgtype true string 此消息类型为固定markdown
title true string 首屏会话透出的展示内容
text true string markdown格式的消息
atMobiles Array 被@人的手机号(在text内容里要有@手机号)
isAtAll bool @所有人时:true,否则为:false

markdown消息

说明:目前只支持md语法的子集,具体支持的元素如下:

标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

引用
> 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

整体跳转ActionCard类型

{
    "actionCard": {
        "title": "乔布斯 20 年前想打造一间苹果咖啡厅,而它正是 Apple Store 的前身", 
        "text": "![screenshot](@lADOpwk3K80C0M0FoA) 
 ### 乔布斯 20 年前想打造的苹果咖啡厅 
 Apple Store 的设计正从原来满满的科技感走向生活化,而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划", 
        "hideAvatar": "0", 
        "btnOrientation": "0", 
        "singleTitle" : "阅读全文",
        "singleURL" : "https://www.dingtalk.com/"
    }, 
    "msgtype": "actionCard"
}
参数 必选 类型 说明
msgtype true string 此消息类型为固定actionCard
title true string 首屏会话透出的展示内容
text true string markdown格式的消息
singleTitle true string 单个按钮的方案。(设置此项和singleURL后btns无效。)
singleURL true string 点击singleTitle按钮触发的URL
btnOrientation false string 0-按钮竖直排列,1-按钮横向排列
hideAvatar false string 0-正常发消息者头像,1-隐藏发消息者头像

通过整体跳转ActionCard类型消息发出的消息样式如下:
image
image

独立跳转ActionCard类型

{
    "actionCard": {
        "title": "乔布斯 20 年前想打造一间苹果咖啡厅,而它正是 Apple Store 的前身", 
        "text": "![screenshot](@lADOpwk3K80C0M0FoA) 
 ### 乔布斯 20 年前想打造的苹果咖啡厅 
 Apple Store 的设计正从原来满满的科技感走向生活化,而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划", 
        "hideAvatar": "0", 
        "btnOrientation": "0", 
        "btns": [
            {
                "title": "内容不错", 
                "actionURL": "https://www.dingtalk.com/"
            }, 
            {
                "title": "不感兴趣", 
                "actionURL": "https://www.dingtalk.com/"
            }
        ]
    }, 
    "msgtype": "actionCard"
}
参数 必选 类型 说明
msgtype true string 此消息类型为固定actionCard
title true string 首屏会话透出的展示内容
text true string markdown格式的消息
btns true array 按钮的信息:title-按钮方案,actionURL-点击按钮触发的URL
btnOrientation false string 0-按钮竖直排列,1-按钮横向排列
hideAvatar false string 0-正常发消息者头像,1-隐藏发消息者头像

通过独立跳转ActionCard类型消息发出的消息样式如下:
image

FeedCard类型

{
    "feedCard": {
        "links": [
            {
                "title": "时代的火车向前开", 
                "messageURL": "https://mp.weixin.qq.com/s?__biz=MzA4NjMwMTA2Ng==&mid=2650316842&idx=1&sn=60da3ea2b29f1dcc43a7c8e4a7c97a16&scene=2&srcid=09189AnRJEdIiWVaKltFzNTw&from=timeline&isappinstalled=0&key=&ascene=2&uin=&devicetype=android-23&version=26031933&nettype=WIFI", 
                "picURL": "https://www.dingtalk.com/"
            },
            {
                "title": "时代的火车向前开2", 
                "messageURL": "https://mp.weixin.qq.com/s?__biz=MzA4NjMwMTA2Ng==&mid=2650316842&idx=1&sn=60da3ea2b29f1dcc43a7c8e4a7c97a16&scene=2&srcid=09189AnRJEdIiWVaKltFzNTw&from=timeline&isappinstalled=0&key=&ascene=2&uin=&devicetype=android-23&version=26031933&nettype=WIFI", 
                "picURL": "https://www.dingtalk.com/"
            }
        ]
    }, 
    "msgtype": "feedCard"
}
参数 必选 类型 说明
msgtype true string 此消息类型为固定feedCard
title true string 单条信息文本
messageURL true string 点击单条信息到跳转链接
picURL true string 单条信息后面图片的URL

通过FeedCard类型消息发出的消息样式如下:
image

测试自定义机器人

通过下面方法,可以快速验证自定义机器人是否可以正常工作:

  • 使用命令行工具curl(版本用最新:7.29.0
curl 'https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx' \
   -H 'Content-Type: application/json' \
   -d '
  {"msgtype": "text", 
    "text": {
        "content": "我就是我, 是不一样的烟火"
     }
  }'
  • Java程序测试
import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;


public class ChatbotSend {

    public static String WEBHOOK_TOKEN = "https://oapi.dingtalk.com/robot/send?access_token=xxxxxx";

    public static void main(String args[]) throws Exception{

        HttpClient httpclient = HttpClients.createDefault();

        HttpPost httppost = new HttpPost(WEBHOOK_TOKEN);
        httppost.addHeader("Content-Type", "application/json; charset=utf-8");

        String textMsg = "{ \"msgtype\": \"text\", \"text\": {\"content\": \"我就是我, 是不一样的烟火\"}}";
        StringEntity se = new StringEntity(textMsg, "utf-8");
        httppost.setEntity(se);

        HttpResponse response = httpclient.execute(httppost);
        if (response.getStatusLine().getStatusCode()== HttpStatus.SC_OK){
            String result= EntityUtils.toString(response.getEntity(), "utf-8");
            System.out.println(result);
        }
    }
}
  • PHP程序测试
<?php  
 
function request_by_curl($remote_server, $post_string) {  
    $ch = curl_init();  
    curl_setopt($ch, CURLOPT_URL, $remote_server);
    curl_setopt($ch, CURLOPT_POST, 1); 
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5); 
    curl_setopt($ch, CURLOPT_HTTPHEADER, array ('Content-Type: application/json;charset=utf-8'));
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);  
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
    // 线下环境不用开启curl证书验证, 未调通情况可尝试添加该代码
    // curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0); 
    // curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
    $data = curl_exec($ch);
    curl_close($ch);  
              
    return $data;  
}  

$webhook = "https://oapi.dingtalk.com/robot/send?access_token=xxxxxx";
$message="我就是我, 是不一样的烟火";
$data = array ('msgtype' => 'text','text' => array ('content' => $message));
$data_string = json_encode($data);

$result = request_by_curl($webhook, $data_string);  
echo $result;

?>

Java SDK

可以下载Java语言的SDK(点击下载)简化各种类型消息的构建,具体用法可以参考源代码里面的demo代码。

消息发送频率限制

每个机器人每分钟最多发送20条。
消息发送太频繁会严重影响群成员的使用体验,大量发消息的场景(譬如系统监控报警)可以将这些信息进行整合,通过markdown消息以摘要的形式发送到群里。

应答机制支持

当前机器人尚不支持应答机制(该机制指的是群里成员在聊天@机器人的时候,钉钉回调指定的服务地址,即Outgoing机器人)。

FAQ

关于此文档暂时还没有FAQ
返回
顶部