跳转到主要内容
调用本接口,使用自定义机器人发送群消息。

接口调用说明

  • 本接口支持自定义机器人在企业内部群和普通群中发送消息,调用本接口前需要创建自定义机器人,可参见开发机器人应用。
  • 如果你有大量发消息的场景(譬如系统监控报警)可以将这些信息进行整合,通过markdown消息以摘要的形式发送到群里。
  • 如果自定义机器人的安全设置使用的是自定义机器人安全设置,调用本接口发送消息时,需要拼接timestamp和sign参数,示例为:
    https://oapi.dingtalk.io/robot/send?access_token=XXXXXX&timestamp=XXX&sign=XXX
    
  • 每个机器人每分钟最多发送20条消息到群里,如果超过20条,会限流10分钟

请求

基本信息
HTTP URLhttps://oapi.dingtalk.io/robot/send
HTTP MethodPOST
支持的应用类型appType-企业内部应用appType-第三方企业应用
权限要求permission-qyapi_base-调用企业API基础权限

查询参数

名称类型是否必填示例值描述
access_tokenStringBE3xxxx自定义机器人调用接口的凭证。 自定义机器人安装后webhook地址中的access_token值。详情参考获取自定义机器人 Webhook 地址

请求体

名称类型是否必填示例值描述
msgtypeStringtext消息类型,自定义机器人可发送的消息类型参见自定义机器人发送消息的消息类型。
msgUuidString123消息幂等key,可用于控制消息幂等。 说明 典型的使用场景:发消息时接口调用超时或未知错误等报错,开发者可使用同一个msgUuid重试,避免重复发出消息。
textObject文本类型消息。
contentString钉钉,让进步发生文本消息的内容。
atObject被@的群成员信息。
isAtAllBooleanfalse是否@所有人。 - true:是 - false:否
atMobilesString[][“15xxx,18xxx”]被@的群成员手机号。
atUserIdsString[][“user001”,“user002”]被@的群成员userId。 说明 在@群成员时,最多只能@50个。
linkObject链接类型消息。
messageUrlStringhttps://www.dingtalk.io点击消息跳转的URL。
titleString这是标题链接消息标题。
picUrlString@aubHxxxxx链接消息内的图片地址,建议使用上传媒体文件接口获取。
textString链接消息的内容链接消息的内容。
markdownObjectmarkdown类型消息。
textStringmarkdown消息内容markdown类型消息的文本内容。
titleString会话列表展示的标题消息会话列表中展示的标题,非消息体的标题。
actionCardObjectactionCard类型消息。
hideAvatarString1是否显示消息发送者头像。 - 0:正常发消息者头像 - 1:隐藏发消息者头像
btnOrientationString1消息内按钮排列方式。 - 0:按钮竖直排列 - 1:按钮横向排列
singleURLStringhttps://www.dingtalk.io点击singleTitle按钮触发的URL。 说明 消息内只有一个按钮时,该参数必填。
singleTitleString这是一个按钮单个按钮的方案。(设置此项和singleURL后btns无效。) 说明 消息内只有一个按钮时,该参数必填。
textString消息内容actionCard类型消息的正文内容,支持markdown语法。
titleString显示到会话列表中的标题消息会话列表中展示的标题,非消息体的标题。
btnsObject[]按钮的信息列表。 说明 消息内不止一个按钮时,该参数必填。
actionURLStringhttps://www.dingtalk.io按钮跳转的URL。
titleString这是一个按钮按钮上显示的文本。
feedCardObjectfeedCard类型消息。
linksObject[]feedCard消息的内容列表。
picURLString@aubHxxxxxfeedCard消息内每条内容的图片URL,建议使用上传媒体文件接口获取。
messageURLStringhttps://www.dingtalk.iofeedCard消息内每条内容上午跳转链接。
titleString消息标题feedCard消息内每条内容的标题。

请求示例

curl -X POST "https://oapi.dingtalk.io/robot/send" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=c370586xxxxd65d506' \
-d 'actionCard=null' \
-d 'at=null' \
-d 'feedCard=null' \
-d 'link=null' \
-d 'markdown=null' \
-d 'msgtype=text' \
-d 'text=null'
Java
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/robot/send");
OapiRobotSendRequest req = new OapiRobotSendRequest();
req.setMsgtype("text");
Text obj1 = new Text();
obj1.setContent("123");
req.setText(obj1);
At obj2 = new At();
obj2.setIsAtAll(false);
obj2.setAtMobiles("");
obj2.setAtUserIds("");
req.setAt(obj2);
Link obj3 = new Link();
obj3.setMessageUrl("1");
obj3.setTitle("1");
obj3.setPicUrl("1");
obj3.setText("1");
req.setLink(obj3);
Markdown obj4 = new Markdown();
obj4.setText("1");
obj4.setTitle("1");
req.setMarkdown(obj4);
Actioncard obj5 = new Actioncard();
obj5.setHideAvatar("1");
obj5.setBtnOrientation("1");
obj5.setSingleURL("1");
obj5.setSingleTitle("1");
obj5.setText("1");
obj5.setTitle("1");
List<Btns> list7 = new ArrayList<Btns>();
Btns obj8 = new Btns();
list7.add(obj8);
obj8.setActionURL("1");
obj8.setTitle("1");
obj5.setBtns(list7);
req.setActionCard(obj5);
Feedcard obj9 = new Feedcard();
List<Links> list11 = new ArrayList<Links>();
Links obj12 = new Links();
list11.add(obj12);
obj12.setPicURL("1");
obj12.setMessageURL("1");
obj12.setTitle("1");
obj9.setLinks(list11);
req.setFeedCard(obj9);
OapiRobotSendResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python
# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiRobotSendRequest("https://oapi.dingtalk.io/robot/send")

req.msgtype="text"
req.text=""
req.at=""
req.link=""
req.markdown=""
req.actionCard=""
req.feedCard=""
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)
PHP
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiRobotSendRequest;
$req->setMsgtype("text");
$text = new Text;
$text->content="123";
$req->setText($text);
$at = new At;
$at->isAtAll="false";
$at->atMobiles="[]";
$at->atUserIds="[]";
$req->setAt($at);
$link = new Link;
$link->messageUrl="1";
$link->title="1";
$link->picUrl="1";
$link->text="1";
$req->setLink($link);
$markdown = new Markdown;
$markdown->text="1";
$markdown->title="1";
$req->setMarkdown($markdown);
$actionCard = new Actioncard;
$actionCard->hideAvatar="1";
$actionCard->btnOrientation="1";
$actionCard->singleURL="1";
$actionCard->singleTitle="1";
$actionCard->text="1";
$actionCard->title="1";
$btns = new Btns;
$btns->actionURL="1";
$btns->title="1";
$actionCard->btns = array($btns);
$req->setActionCard($actionCard);
$feedCard = new Feedcard;
$links = new Links;
$links->picURL="1";
$links->messageURL="1";
$links->title="1";
$feedCard->links = array($links);
$req->setFeedCard($feedCard);
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/robot/send");
C#
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/robot/send");
OapiRobotSendRequest req = new OapiRobotSendRequest();
req.Msgtype = "text";
OapiRobotSendRequest.TextDomain obj1 = new OapiRobotSendRequest.TextDomain();
obj1.Content = "123";
req.Text_ = obj1;
OapiRobotSendRequest.AtDomain obj2 = new OapiRobotSendRequest.AtDomain();
obj2.IsAtAll = false;
obj2.AtMobiles = "";
obj2.AtUserIds = "";
req.At_ = obj2;
OapiRobotSendRequest.LinkDomain obj3 = new OapiRobotSendRequest.LinkDomain();
obj3.MessageUrl = "1";
obj3.Title = "1";
obj3.PicUrl = "1";
obj3.Text = "1";
req.Link_ = obj3;
OapiRobotSendRequest.MarkdownDomain obj4 = new OapiRobotSendRequest.MarkdownDomain();
obj4.Text = "1";
obj4.Title = "1";
req.Markdown_ = obj4;
OapiRobotSendRequest.ActioncardDomain obj5 = new OapiRobotSendRequest.ActioncardDomain();
obj5.HideAvatar = "1";
obj5.BtnOrientation = "1";
obj5.SingleURL = "1";
obj5.SingleTitle = "1";
obj5.Text = "1";
obj5.Title = "1";
List<OapiRobotSendRequest.BtnsDomain> list7 = new List<OapiRobotSendRequest.BtnsDomain>();
OapiRobotSendRequest.BtnsDomain obj8 = new OapiRobotSendRequest.BtnsDomain();
list7.Add(obj8);
obj8.ActionURL = "1";
obj8.Title = "1";
obj5.Btns= list7;
req.ActionCard_ = obj5;
OapiRobotSendRequest.FeedcardDomain obj9 = new OapiRobotSendRequest.FeedcardDomain();
List<OapiRobotSendRequest.LinksDomain> list11 = new List<OapiRobotSendRequest.LinksDomain>();
OapiRobotSendRequest.LinksDomain obj12 = new OapiRobotSendRequest.LinksDomain();
list11.Add(obj12);
obj12.PicURL = "1";
obj12.MessageURL = "1";
obj12.Title = "1";
obj9.Links= list11;
req.FeedCard_ = obj9;
OapiRobotSendResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

响应

响应体

名称类型示例值描述
errmsgStringok错误码描述。
errcodeNumber0错误码。

响应体示例

{
  "errcode":"0",
  "errmsg":"ok"
}

错误码

若调用该接口报错,可根据错误信息在全局错误码文档中查找解决方案。
错误码(errorcode)错误码描述(errmsg)解决方案
-1系统繁忙请稍后重试
40035缺少参数 json请补充消息json
43004无效的HTTP HEADER Content-Type请设置具体的消息参数
400013群已被解散请向其他群发消息
400101access_token不存在请确认access_token拼写是否正确
400102机器人已停用请联系管理员启用机器人
400105不支持的消息类型请使用文档中支持的消息类型
400106机器人不存在请确认机器人是否在群中
410100发送速度太快而限流请降低发送速度
430101含有不安全的外链请确认发送的内容合法
430102含有不合适的文本请确认发送的内容合法
430103含有不合适的图片请确认发送的内容合法
430104含有不合适的内容请确认发送的内容合法
当出现以下错误时,表示消息校验未通过,请查看机器人的安全设置。
错误码(errorcode)错误码描述(errmsg)解决方案
310000- keywords not in content - invalid timestamp - sign not match - ip X.X.X.X not in whitelist- 消息内容中不包含任何关键词 - timestamp 无效 - 签名不匹配 - IP 地址不在白名单