钉钉开发文档

工作通知消息

更新时间: 2019-7-11

工作通知消息是以企业工作通知会话中某个微应用的名义推送到员工的通知消息,例如审批通知、任务通知、工作项通知等。下图是工作通知的会话和消息示例:
11.png

发送工作通知消息

发送工作通知消息需要注意以下事项:

  • 同一个微应用相同消息的内容同一个用户一天只能接收一次。
  • 同一个微应用给同一个用户发送消息,企业内部开发方式一天不得超过500次。
  • 通过设置to_all_user参数全员推送消息,一天最多3次。
  • 详细的限制说明,请参考“工作通知消息的限制”。
  • 该接口是异步发送消息,接口返回成功并不表示用户一定会收到消息,需要通过“查询工作通知消息的发送结果”接口查询是否给用户发送成功。
  • 消息类型和样例可参考消息类型文档。

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

名称 类型 是否必须 示例值 描述
agent_id Number 必须 1234 应用agentId
userid_list String 可选(userid_list,dept_id_list, to_all_user必须有一个不能为空) zhangsan,lisi 接收者的用户userid列表,最大列表长度:100
dept_id_list String 可选(可不传,若传不能为空) 123,456 接收者的部门id列表,最大列表长度:20,  接收者是部门id下(包括子部门下)的所有用户
to_all_user Boolean 可选 false 是否发送给企业全部用户
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

工作通知消息撤回

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

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

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/recall");
OapiMessageCorpconversationRecallRequest request = new OapiMessageCorpconversationRecallRequest();
request.setAgentId(237990693L);
request.setMsgTaskId(3568141183L);
OapiMessageCorpconversationRecallResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!