发送工作通知

调用本接口发送工作通知消息。

工作通知消息是以某个应用的名义推送到员工的工作通知消息，例如生日祝福、入职提醒等。可以发送文本、语音、链接等，消息类型和样例可参考消息类型与数据格式。

工作通知

使用场景

重要

2020年11月27日以后创建的第三方企业应用，请调用使用模板发送工作通知消息接口发送工作通知。

  • 适用场景：适用于发送通知类的消息，不包含审批任务等。

  • 不适用场景：需要发送一条任务类的通知提醒给员工，比如审批任务等，调用此接口无法实现。这种场景可以使用发起待办任务类接口。

发送工作通知消息接口调用频率限制

超出以下限制次数后，接口返回成功，但用户无法接收到。

说明

详细的限制说明，请参考发送消息频率限制。

  • 企业内部应用发送消息单次最多只能给5000人发送，第三方企业应用发送消息单次最多能给1000人发送。

  • 给同一员工一天只能发送一条内容相同的消息通知。

  • 企业内部应用每天给每个员工最多可发送500条消息通知，第三方企业应用最多可发送100条。

  • 企业内部应用或第三方企业应用发送消息时，每分钟最多有5000人可以接收到消息。

接口使用说明

如果接口发送成功，接收人没有收到信息，可调用获取工作通知消息的发送结果查询结果，并对比文档中的返回错误码。

权限

服务端API是以应用维度授权的，在创建应用时，系统已默认添加了消息通知权限。

应用类型

是否支持调用

权限申请方式

API Explorer调试

企业内部应用

是

无需申请

调试

第三方企业应用

是

无需申请

调试

第三方个人应用

否

—

—

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2

Query参数

名称

类型

是否必填

示例值

描述

access_token

String

是

6d1bxxxx

调用该接口的应用凭证。

Body参数

名称

类型

是否必填

示例值

描述

agent_id

Long

是

123L

发送消息时使用的微应用的AgentID。

userid_list

String

否

user123,user456

接收者的userid列表，最大用户列表长度100。

dept_id_list

String

否

123,345

接收者的部门id列表，最大列表长度20。

接收者是部门ID时，包括子部门下的所有用户。

to_all_user

Boolean

否

false

是否发送给企业全部用户。

说明

当设置为false时必须指定userid_list或dept_id_list其中一个参数的值。

msg

JSON Object

是

{ "msgtype": "text", "text": { "content": "请提交日报。" } }

消息内容，最长不超过2048个字节，支持以下工作通知类型，msgtype 包括：

  • text：文本消息

  • image：图片消息

  • voice：语音消息

  • file：文件消息

  • link：链接消息

  • oa：OA消息

    重要

    OA消息支持通过status_bar参数设置消息的状态文案和颜色，消息发送后可调用更新工作通知状态栏接口更新消息状态和颜色。

  • markdown：Markdown消息

  • action_card：卡片消息

说明

返回参数

名称

类型

示例值

描述

request_id

String

4jzllmte0wau

请求ID。

errmsg

String

ok

返回码描述。

重要

如果接口发送成功，接收人没有收到信息，可调用获取工作通知消息的发送结果查询结果，并对比文档中的返回错误码。

errcode

Number

0

返回码。

task_id

Number

256271667526

创建的异步发送任务ID。

示例

请求示例（HTTP）

POST https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=ACCESS_TOKEN

请求正文

{
        "msg":{
                "voice":{
                        "duration":"100",
                        "media_id":"100"
                },
                "image":{
                        "media_id":"@123"
                },
                "oa":{
                        "head":{
                                "bgcolor":"bgcolor",
                                "text":"text"
                        },
                        "pc_message_url":"pc_message_url",
                        "status_bar":{
                                "status_value":"进行中",
                                "status_bg":"0xFFF65E5E"
                        },
                        "body":{
                                "file_count":"file_count",
                                "image":"image",
                                "form":{
                                        "value":"value",
                                        "key":"key"
                                },
                                "author":"author",
                                "rich":{
                                        "unit":"unit",
                                        "num":"num"
                                },
                                "title":"title",
                                "content":"content"
                        },
                        "message_url":"message_url"
                },
                "file":{
                        "media_id":"media_id"
                },
                "action_card":{
                        "btn_json_list":{
                                "action_url":"action_url",
                                "title":"title"
                        },
                        "single_url":"single_url",
                        "btn_orientation":"btn_orientation",
                        "single_title":"single_title",
                        "markdown":"markdown",
                        "title":"title"
                },
                "link":{
                        "picUrl":"picUrl",
                        "messageUrl":"messageUrl",
                        "text":"text",
                        "title":"title"
                },
                "markdown":{
                        "text":"text",
                        "title":"title"
                },
                "text":{
                        "content":"123"
                },
                "msgtype":"text"
        },
        "to_all_user":"false",
        "agent_id":"123",
        "dept_id_list":"123,456",
        "userid_list":"123,456"
}

请求示例（JAVA SDK）

  • text（文本消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendTextMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • image（图片消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendImageMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • voice（语音消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendVoiceMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

        OapiMessageCorpconversationAsyncsendV2Request.Msg msg = new OapiMessageCorpconversationAsyncsendV2Request.Msg();
        msg.setMsgtype("voice");
        OapiMessageCorpconversationAsyncsendV2Request.Voice voice = new OapiMessageCorpconversationAsyncsendV2Request.Voice();
        voice.setMediaId("@lADOdvRYes0CbM0CbA"); // 语音文件mediaId
        voice.setDuration("10"); // 语音时长，单位秒，类型为String
        msg.setVoice(voice);
        request.setMsg(msg);

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • file（文件消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendFileMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • link（链接消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendLinkMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • oa（OA消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendOAMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

        OapiMessageCorpconversationAsyncsendV2Request.Msg msg = new OapiMessageCorpconversationAsyncsendV2Request.Msg();
        msg.setMsgtype("oa");
        OapiMessageCorpconversationAsyncsendV2Request.OA oa = new OapiMessageCorpconversationAsyncsendV2Request.OA();
        OapiMessageCorpconversationAsyncsendV2Request.Head head = new OapiMessageCorpconversationAsyncsendV2Request.Head();
        head.setText("head");
        oa.setHead(head);
        OapiMessageCorpconversationAsyncsendV2Request.Body body = new OapiMessageCorpconversationAsyncsendV2Request.Body();
        body.setContent("xxx");
        oa.setBody(body);
        msg.setOa(oa);
        request.setMsg(msg);

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • markdown（Markdown消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendMarkdownMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

  • action_card（卡片消息）

    import com.dingtalk.api.DefaultDingTalkClient;
import com.dingtalk.api.DingTalkClient;
import com.dingtalk.api.request.OapiMessageCorpconversationAsyncsendV2Request;
import com.dingtalk.api.response.OapiMessageCorpconversationAsyncsendV2Response;

public class SendActionCardMsg {
    public static void main(String[] args) throws Exception {
        String accessToken = "737e494d3d8236a5a9a248e20e650bef";
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(2839445214L);
        request.setUseridList("0147282552401293909,manager4974");
        request.setToAllUser(false);

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

        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, accessToken);
        System.out.println(rsp.getBody());
    }
}

返回示例

{
        "errcode":0,
        "task_id":256271667526,
        "request_id":"4jzllmte0wau"
}