钉钉开发文档

工作通知消息

更新时间: 2019-1-7

发送工作通知消息

  • 同一个微应用相同消息内容同一个用户一天只能接收一次,重复发送会发送成功但用户接收不到。
  • 该接口是异步发送消息,接口返回成功并不表示用户收到消息,需要通过“查询工作通知消息的发送结果”接口查询是否给用户发送成功。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
agent_id Number 必须 1234 企业自建应用是微应用agentId,第三方应用是通过获取授权企业的应用信息接口/service/get_agent获取到的agentId
userid_list String 可选(userid_list,dept_id_list, to_all_user必须有一个不能为空) zhangsan,lisi 接收者的用户userid列表,最大列表长度:20
dept_id_list String 可选 123,456 接收者的部门id列表,最大列表长度:20,  接收者是部门id下(包括子部门下)的所有用户
to_all_user Boolean 可选 false 是否发送给企业全部用户(ISV不能设置true)
msg json对象 必须 {"msgtype":"text","text":{"content":"消息内容"}} 消息内容,具体见“消息类型与数据格式”。最长不超过2048个字节

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");

OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
request.setUseridList("01376814877479");
request.setAgentId(153858650L);
request.setToAllUser(false);

OapiMessageCorpconversationAsyncsendV2Request.Msg msg = new OapiMessageCorpconversationAsyncsendV2Request.Msg();
msg.setMsgtype("text");
msg.setText(new OapiMessageCorpconversationAsyncsendV2Request.Text());
msg.getText().setContent("test123");
request.setMsg(msg);

msg.setMsgtype("image");
msg.setImage(new OapiMessageCorpconversationAsyncsendV2Request.Image());
msg.getImage().setMediaId("@lADOdvRYes0CbM0CbA");
request.setMsg(msg);

msg.setMsgtype("file");
msg.setFile(new OapiMessageCorpconversationAsyncsendV2Request.File());
msg.getFile().setMediaId("@lADOdvRYes0CbM0CbA");
request.setMsg(msg);

msg.setMsgtype("link");
msg.setLink(new OapiMessageCorpconversationAsyncsendV2Request.Link());
msg.getLink().setTitle("test");
msg.getLink().setText("test");
msg.getLink().setMessageUrl("test");
msg.getLink().setPicUrl("test");
request.setMsg(msg);

msg.setMsgtype("markdown");
msg.setMarkdown(new OapiMessageCorpconversationAsyncsendV2Request.Markdown());
msg.getMarkdown().setText("##### text");
msg.getMarkdown().setTitle("### Title");
request.setMsg(msg);

msg.setOa(new OapiMessageCorpconversationAsyncsendV2Request.OA());
msg.getOa().setHead(new OapiMessageCorpconversationAsyncsendV2Request.Head());
msg.getOa().getHead().setText("head");
msg.getOa().setBody(new OapiMessageCorpconversationAsyncsendV2Request.Body());
msg.getOa().getBody().setContent("xxx");
msg.setMsgtype("oa");
request.setMsg(msg);

msg.setActionCard(new OapiMessageCorpconversationAsyncsendV2Request.ActionCard());
msg.getActionCard().setTitle("xxx123411111");
msg.getActionCard().setMarkdown("### 测试123111");
msg.getActionCard().setSingleTitle("测试测试");
msg.getActionCard().setSingleUrl("https://www.baidu.com");
msg.setMsgtype("action_card");
request.setMsg(msg);

OapiMessageCorpconversationAsyncsendV2Response response = client.execute(request,accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "task_id":123
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
task_id 创建的发送任务id

查询工作通知消息的发送进度

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
agent_id Number 必须 123 发送消息时使用的微应用的id
task_id Number 必须 456 发送消息时钉钉返回的任务id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress");
OapiMessageCorpconversationGetsendprogressRequest request  = new OapiMessageCorpconversationGetsendprogressRequest();
request.setAgentId(135717601L);
request.setTaskId(9326688016L);
OapiMessageCorpconversationGetsendprogressResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "progress":{
        "progress_in_percent":100,
        "status":2
    }
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
progress
└ progress_in_percent 取值 0-100,表示处理的百分比
└ status 任务执行状态,0=未开始,1=处理中,2=处理完毕

查询工作通知消息的发送结果

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
agent_id Number 可选 123 微应用的agentid
task_id Number 可选 456 异步任务的id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult");
OapiMessageCorpconversationGetsendresultRequest request  = new OapiMessageCorpconversationGetsendresultRequest();
request.setAgentId(135717601L);
request.setTaskId(9326688016L);
OapiMessageCorpconversationGetsendresultResponse response = client.execute(request, accessToken);

返回结果

{
    "send_result":{
        "invalid_user_id_list":"zhangsan,lisi",
        "forbidden_user_id_list":"zhangsan,lisi",
        "failed_user_id_list":"zhangsan,lisi",
        "read_user_id_list":"zhangsan,lisi",
        "unread_user_id_list":"zhangsan,lisi",
        "invalid_dept_id_list":"1,2,3"
    },
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
send_result
└ invalid_user_id_list 无效的用户id
└ forbidden_user_id_list 因发送消息过于频繁或超量而被流控过滤后实际未发送的userid。未被限流的接收者仍会被成功发送。限流规则包括:1、给同一用户发相同内容消息一天仅允许一次;2、如果是ISV接入方式,给同一用户发消息一天不得超过50次;如果是企业接入方式,此上限为500
└ failed_user_id_list 发送失败的用户id
└ read_user_id_list 已读消息的用户id
└ unread_user_id_list 未读消息的用户id
└ invalid_dept_id_list 无效的部门id
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!