文档中心 > API类目 > 钉钉API

dingtalk.oapi.message.mass.send (互动服务窗消息群发接口)

互动服务窗消息群发接口

公共参数

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

名称	类型	是否必须	描述
access_token	String	是	钉钉提供的授权Token，想了解详情，ISV开发者请点击这里，企业开发者请点击这里。若有疑问，咨询邮箱dingding_open_dingtalk#list.alibaba-inc.com。

请求参数

名称	类型	是否必须	示例值	更多限制	描述
unionid	String	必须	jYdrJoCmTo0iE	最大长度：128	服务号的unionid
media_id	String	可选	P16mHftLYX8iE	最大长度：256	消息卡片素材id
is_to_all	Boolean	必须	true		是否群发给所有订阅者，true-是，false-否
msg_type	String	必须	text	最大长度：32	msg_type, 消息类型：text，文本类型，此时文本内容填在text_content字段中；news_card，消息卡片，此时的media_id通过消息卡片上传接口得到； image，图片，此时的media_id通过图片上传接口得到
text_content	String	可选	hello	最大长度：65535	文本内容，当msg_type为text时有效
uuid	String	必须	48566508-3f35-4473-8452-61fe00348152	最大长度：128	调用时填写随机生成的UUID, 防止消息重复发送
userid_list	String []	可选	zhangsan,lisi	最大列表长度：10000	接收者的用户userid列表
dep_id_list	Number []	可选	123,456	最大列表长度：2000	接收者的部门id列表，接收者是部门id下(包括子部门下)的所有用户
is_preview	Boolean	可选	true	默认值：false	是否预览推送
msg_body	MessageBody	可选			消息体
voice Voice 可选语音消息 └ duration Number 可选 1 正整数，小于60，表示音频时长 └ media_id String 可选 @lALPDeC2uOPVEsvNAVjNAVg 媒体文件id。2MB，播放长度不超过60s，AMR格式 oa OA 可选 oa消息 head Head 可选消息头部内容 └ bgcolor String 可选 11111111 消息头部的背景颜色。长度限制为8个英文字符，其中前2为表示透明度，后6位表示颜色值。不要添加0x └ text String 可选 head text 消息的头部标题 (向普通会话发送时有效，向企业会话发送时会被替换为微应用的名字)，长度限制为最多10个字符 └ message_url String 可选 https://dingtalk.com 消息点击链接地址，当发送消息为小程序时支持小程序跳转链接 body Body 可选消息体 └ image String 可选 @lALPDeC2uOPVEsvNAVjNAVg 消息体中的图片，支持图片资源@mediaId form FormItem [] 可选消息体的表单，最多显示6个，超过会被隐藏 └ key String 可选 key1 消息体的关键字 └ value String 可选 value1 消息体的关键字对应的值 └ author String 可选 rick 自定义的作者名字 rich RichText 可选单行富文本信息 └ unit String 可选 kg 单行富文本信息的单位 └ num String 可选 10 单行富文本信息的数目 └ title String 可选 titile 消息体的标题，建议50个字符以内 └ file_count Number 可选 2 自定义的附件数目。此数字仅供显示，钉钉不作验证 └ content String 可选 hello 消息体的内容，最多显示3行 └ pc_message_url String 可选 https://dingtalk.com PC端点击消息时跳转到的地址 file File 可选文件消息 └ media_id String 可选 @lALPDeC2uOPVEsvNAVjNAVg 媒体文件id。引用的媒体文件最大10MB link Link 可选链接消息 └ title String 可选 hello title 消息标题，建议100字符以内 └ cover_image String 可选 @lALPDeC2uOPVEsvNAVjNAVg 图片地址 └ link_url String 可选 https://dingtalk.com 消息点击链接地址，当发送消息为小程序时支持小程序跳转链接 └ summary String 可选 link消息描述消息描述，建议500字符以内 └ open_type Number 可选 0 默认值：0 链接打开方式 0 -端外浏览器打开，1-端内浏览器打开 markdown Markdown 可选 markdown消息 └ text String 可选 markdown text markdown格式的消息，建议5000字符以内 └ title String 可选 title 首屏会话透出的展示内容 action_card ActionCard 可选 action_card卡片消息 └ btn_orientation String 可选 0 使用独立跳转ActionCard样式时的按钮排列方式，竖直排列(0)，横向排列(1)；必须与button_list同时设置 └ single_title String 可选 single title 使用整体跳转ActionCard样式时的标题，必须与single_url同时设置，最长20个字符 └ markdown String 可选 markdown text 消息内容，支持markdown，语法参考标准markdown语法。建议1000个字符以内 button_list Button [] 可选使用独立跳转ActionCard样式时的按钮列表；必须与btn_orientation同时设置 └ title String 可选 btn_title1 使用独立跳转ActionCard样式时的按钮的标题，最长20个字符 └ action_url String 可选 btn_action_url1 消息点击链接地址，当发送消息为小程序时支持小程序跳转链接，最长500个字符 └ single_url String 可选 https://dingtalk.com 消息点击链接地址，当发送消息为小程序时支持小程序跳转链接，最长500个字符 └ title String 可选 title 透出到会话列表和通知的文案，最长64个字符
roleIds	Number []	可选	1,2	最大列表长度：999	角色id,通过开放平台角色列表查询

响应参数

名称	类型	示例值	描述
errmsg	String	ok	错误信息
errcode	Number	0	错误码
task_id	String	106689	推送任务id

请求示例

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/mass/send");
OapiMessageMassSendRequest req = new OapiMessageMassSendRequest();
req.setUnionid("jYdrJoCmTo0iE");
req.setMediaId("P16mHftLYX8iE");
req.setIsToAll(true);
req.setMsgType("text");
req.setTextContent("hello");
req.setUuid("48566508-3f35-4473-8452-61fe00348152");
req.setUseridList("zhangsan,lisi");
req.setDepIdList("123,456");
req.setIsPreview(true);
MessageBody obj1 = new MessageBody();
Voice obj2 = new Voice();
obj2.setDuration(1L);
obj2.setMediaId("@lALPDeC2uOPVEsvNAVjNAVg");
obj1.setVoice(obj2);
OA obj3 = new OA();
Head obj4 = new Head();
obj4.setBgcolor("11111111");
obj4.setText("head text");
obj3.setHead(obj4);
obj3.setMessageUrl("https://dingtalk.com");
Body obj5 = new Body();
obj5.setImage("@lALPDeC2uOPVEsvNAVjNAVg");
List<FormItem> list7 = new ArrayList<FormItem>();
FormItem obj8 = new FormItem();
list7.add(obj8);
obj8.setKey("key1");
obj8.setValue("value1");
obj5.setForm(list7);
obj5.setAuthor("rick");
RichText obj9 = new RichText();
obj9.setUnit("kg");
obj9.setNum("10");
obj5.setRich(obj9);
obj5.setTitle("titile");
obj5.setFileCount(2L);
obj5.setContent("hello");
obj3.setBody(obj5);
obj3.setPcMessageUrl("https://dingtalk.com");
obj1.setOa(obj3);
File obj10 = new File();
obj10.setMediaId("@lALPDeC2uOPVEsvNAVjNAVg");
obj1.setFile(obj10);
Link obj11 = new Link();
obj11.setTitle("hello title");
obj11.setCoverImage("@lALPDeC2uOPVEsvNAVjNAVg");
obj11.setLinkUrl("https://dingtalk.com");
obj11.setSummary("link消息描述");
obj11.setOpenType(0L);
obj1.setLink(obj11);
Markdown obj12 = new Markdown();
obj12.setText("markdown text");
obj12.setTitle("title");
obj1.setMarkdown(obj12);
ActionCard obj13 = new ActionCard();
obj13.setBtnOrientation("0");
obj13.setSingleTitle("single title");
obj13.setMarkdown("markdown text");
List<Button> list15 = new ArrayList<Button>();
Button obj16 = new Button();
list15.add(obj16);
obj16.setTitle("btn_title1");
obj16.setActionUrl("btn_action_url1");
obj13.setButtonList(list15);
obj13.setSingleUrl("https://dingtalk.com");
obj13.setTitle("title");
obj1.setActionCard(obj13);
req.setMsgBody(obj1);
req.setRoleIds("1,2");
OapiMessageMassSendResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/mass/send");
OapiMessageMassSendRequest req = new OapiMessageMassSendRequest();
req.Unionid = "jYdrJoCmTo0iE";
req.MediaId = "P16mHftLYX8iE";
req.IsToAll = true;
req.MsgType = "text";
req.TextContent = "hello";
req.Uuid = "48566508-3f35-4473-8452-61fe00348152";
req.UseridList = "zhangsan,lisi";
req.DepIdList = "123,456";
req.IsPreview = true;
OapiMessageMassSendRequest.MessageBodyDomain obj1 = new OapiMessageMassSendRequest.MessageBodyDomain();
OapiMessageMassSendRequest.VoiceDomain obj2 = new OapiMessageMassSendRequest.VoiceDomain();
obj2.Duration = 1L;
obj2.MediaId = "@lALPDeC2uOPVEsvNAVjNAVg";
obj1.Voice= obj2;
OapiMessageMassSendRequest.OADomain obj3 = new OapiMessageMassSendRequest.OADomain();
OapiMessageMassSendRequest.HeadDomain obj4 = new OapiMessageMassSendRequest.HeadDomain();
obj4.Bgcolor = "11111111";
obj4.Text = "head text";
obj3.Head= obj4;
obj3.MessageUrl = "https://dingtalk.com";
OapiMessageMassSendRequest.BodyDomain obj5 = new OapiMessageMassSendRequest.BodyDomain();
obj5.Image = "@lALPDeC2uOPVEsvNAVjNAVg";
List<OapiMessageMassSendRequest.FormItemDomain> list7 = new List<OapiMessageMassSendRequest.FormItemDomain>();
OapiMessageMassSendRequest.FormItemDomain obj8 = new OapiMessageMassSendRequest.FormItemDomain();
list7.Add(obj8);
obj8.Key = "key1";
obj8.Value = "value1";
obj5.Form= list7;
obj5.Author = "rick";
OapiMessageMassSendRequest.RichTextDomain obj9 = new OapiMessageMassSendRequest.RichTextDomain();
obj9.Unit = "kg";
obj9.Num = "10";
obj5.Rich= obj9;
obj5.Title = "titile";
obj5.FileCount = 2L;
obj5.Content = "hello";
obj3.Body= obj5;
obj3.PcMessageUrl = "https://dingtalk.com";
obj1.Oa= obj3;
OapiMessageMassSendRequest.FileDomain obj10 = new OapiMessageMassSendRequest.FileDomain();
obj10.MediaId = "@lALPDeC2uOPVEsvNAVjNAVg";
obj1.File= obj10;
OapiMessageMassSendRequest.LinkDomain obj11 = new OapiMessageMassSendRequest.LinkDomain();
obj11.Title = "hello title";
obj11.CoverImage = "@lALPDeC2uOPVEsvNAVjNAVg";
obj11.LinkUrl = "https://dingtalk.com";
obj11.Summary = "link消息描述";
obj11.OpenType = 0L;
obj1.Link= obj11;
OapiMessageMassSendRequest.MarkdownDomain obj12 = new OapiMessageMassSendRequest.MarkdownDomain();
obj12.Text = "markdown text";
obj12.Title = "title";
obj1.Markdown= obj12;
OapiMessageMassSendRequest.ActionCardDomain obj13 = new OapiMessageMassSendRequest.ActionCardDomain();
obj13.BtnOrientation = "0";
obj13.SingleTitle = "single title";
obj13.Markdown = "markdown text";
List<OapiMessageMassSendRequest.ButtonDomain> list15 = new List<OapiMessageMassSendRequest.ButtonDomain>();
OapiMessageMassSendRequest.ButtonDomain obj16 = new OapiMessageMassSendRequest.ButtonDomain();
list15.Add(obj16);
obj16.Title = "btn_title1";
obj16.ActionUrl = "btn_action_url1";
obj13.ButtonList= list15;
obj13.SingleUrl = "https://dingtalk.com";
obj13.Title = "title";
obj1.ActionCard= obj13;
req.MsgBody_ = obj1;
req.RoleIds = "1,2";
OapiMessageMassSendResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiMessageMassSendRequest;
$req->setUnionid("jYdrJoCmTo0iE");
$req->setMediaId("P16mHftLYX8iE");
$req->setIsToAll("true");
$req->setMsgType("text");
$req->setTextContent("hello");
$req->setUuid("48566508-3f35-4473-8452-61fe00348152");
$req->setUseridList("zhangsan,lisi");
$req->setDepIdList("123,456");
$req->setIsPreview("true");
$msg_body = new MessageBody;
$voice = new Voice;
$voice->duration="1";
$voice->media_id="@lALPDeC2uOPVEsvNAVjNAVg";
$msg_body->voice = $voice;
$oa = new OA;
$head = new Head;
$head->bgcolor="11111111";
$head->text="head text";
$oa->head = $head;
$oa->message_url="https://dingtalk.com";
$body = new Body;
$body->image="@lALPDeC2uOPVEsvNAVjNAVg";
$form = new FormItem;
$form->key="key1";
$form->value="value1";
$body->form = array($form);
$body->author="rick";
$rich = new RichText;
$rich->unit="kg";
$rich->num="10";
$body->rich = $rich;
$body->title="titile";
$body->file_count="2";
$body->content="hello";
$oa->body = $body;
$oa->pc_message_url="https://dingtalk.com";
$msg_body->oa = $oa;
$file = new File;
$file->media_id="@lALPDeC2uOPVEsvNAVjNAVg";
$msg_body->file = $file;
$link = new Link;
$link->title="hello title";
$link->cover_image="@lALPDeC2uOPVEsvNAVjNAVg";
$link->link_url="https://dingtalk.com";
$link->summary="link消息描述";
$link->open_type="0";
$msg_body->link = $link;
$markdown = new Markdown;
$markdown->text="markdown text";
$markdown->title="title";
$msg_body->markdown = $markdown;
$action_card = new ActionCard;
$action_card->btn_orientation="0";
$action_card->single_title="single title";
$action_card->markdown="markdown text";
$button_list = new Button;
$button_list->title="btn_title1";
$button_list->action_url="btn_action_url1";
$action_card->button_list = array($button_list);
$action_card->single_url="https://dingtalk.com";
$action_card->title="title";
$msg_body->action_card = $action_card;
$req->setMsgBody($msg_body);
$req->setRoleIds("1,2");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.com/topapi/message/mass/send");

curl -X POST "https://oapi.dingtalk.com/topapi/message/mass/send" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=342ff757-9000-4b76-9c3e-d286bbb0e1f2' \
-d 'dep_id_list=123%2C456' \
-d 'is_preview=true' \
-d 'is_to_all=true' \
-d 'media_id=P16mHftLYX8iE' \
-d 'msg_body=null' \
-d 'msg_type=text' \
-d 'roleIds=1%2C2' \
-d 'text_content=hello' \
-d 'unionid=jYdrJoCmTo0iE' \
-d 'userid_list=zhangsan%2Clisi' \
-d 'uuid=48566508-3f35-4473-8452-61fe00348152'

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiMessageMassSendRequest("https://oapi.dingtalk.com/topapi/message/mass/send")

req.unionid="jYdrJoCmTo0iE"
req.media_id="P16mHftLYX8iE"
req.is_to_all=true
req.msg_type="text"
req.text_content="hello"
req.uuid="48566508-3f35-4473-8452-61fe00348152"
req.userid_list="zhangsan,lisi"
req.dep_id_list="123,456"
req.is_preview=true
req.msg_body=""
req.roleIds="1,2"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

pTopRequest pRequest = alloc_top_request();
pTopResponse pResponse = NULL;
pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret);
set_api_name(pRequest,"dingtalk.oapi.message.mass.send");
add_param(pRequest,"unionid","jYdrJoCmTo0iE");
add_param(pRequest,"media_id","P16mHftLYX8iE");
add_param(pRequest,"is_to_all","true");
add_param(pRequest,"msg_type","text");
add_param(pRequest,"text_content","hello");
add_param(pRequest,"uuid","48566508-3f35-4473-8452-61fe00348152");
add_param(pRequest,"userid_list","zhangsan,lisi");
add_param(pRequest,"dep_id_list","123,456");
add_param(pRequest,"is_preview","true");
add_param(pRequest,"msg_body","数据结构JSON示例");
add_param(pRequest,"roleIds","1,2");
pResponse = top_execute(pClient,pRequest,sessionKey);
printf("ret code:%d\n",pResponse->code);
if(pResponse->code == 0){
	pTopResponseIterator ite = init_response_iterator(pResponse);
	pResultItem pResultItem = alloc_result_item();
	while(parseNext(ite, pResultItem) == 0){
		printf("%s:%s\n",pResultItem->key,pResultItem->value);
	}
	destroy_response_iterator(ite);
	destroy_result_item(pResultItem);
}
destroy_top_request(pRequest);
destroy_top_response(pResponse);
destroy_taobao_client(pClient);

TopClient = require('./topClient').TopClient;
var client = new TopClient({
	'appkey': 'appkey',
	'appsecret': 'secret',
	'REST_URL': 'http://gw.api.taobao.com/router/rest'
});

client.execute('dingtalk.oapi.message.mass.send', {
	'unionid':'jYdrJoCmTo0iE',
	'media_id':'P16mHftLYX8iE',
	'is_to_all':'true',
	'msg_type':'text',
	'text_content':'hello',
	'uuid':'48566508-3f35-4473-8452-61fe00348152',
	'userid_list':'zhangsan,lisi',
	'dep_id_list':'123,456',
	'is_preview':'true',
	'msg_body':'数据结构JSON示例',
	'roleIds':'1,2'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

响应示例

JSON示例

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

异常示例

JSON示例

{
	"errcode":88,
	"errmsg":"ding talk error"
}

错误码解释

错误码	错误描述	解决方案

API工具

API测试工具错误码查询工具 SDK下载

如何获得此API

FAQ

我要提问

返回
顶部

淘宝开放平台

钉钉API

dingtalk.oapi.message.mass.send (互动服务窗消息群发接口)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ