Skip to main content
Call this API to send a Work Notification message.

​
API call description

A Work Notification is a message pushed to employees on behalf of an app, such as birthday greetings or onboarding reminders. You can send text, voice, links, and more. For message types and samples, refer to Message notification types.
If the API call succeeds but the recipient does not receive the message, call Get the result of sending messages asynchronously to the enterprise to query the result and compare it with the error codes listed in the documentation.

​
Use cases

​
Important

  • Applicable scenarios: Suitable for sending notification-type messages, excluding Approval tasks.
  • Inapplicable scenarios: When you need to send a task-type notification reminder to an employee, such as an Approval task, this API cannot meet the requirement. For such scenarios, use the Create To-Do API instead.

​
Rate limit

​
After the following limits are exceeded, the API returns success, but users cannot receive the messages.

For detailed restrictions, refer to API rate limit.
  • An internal app can send messages to a maximum of 5,000 recipients per call, while a third-party enterprise app can send messages to a maximum of 1,000 recipients per call.
  • Only one message notification with the same content can be sent to the same employee per day.
  • An internal app can send up to 500 message notifications per employee per day, and a third-party enterprise app can send up to 100.
  • When an internal app or a third-party enterprise app sends messages, up to 5,000 recipients can receive messages per minute.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Permission requirementspermission-qyapi_base-Basic permission required to call enterprise APIs

​
Query parameter

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe app credential used to call this API. - For an internal app, obtain it through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for getting the access_token of a third-party enterprise.

​
Request body

NameTypeRequiredExampleDescription
agent_idLongYes123LThe Agent ID of the micro app used to send the message. - For an internal app, view it on the app details page in the Developer Backend. - For a third-party enterprise app, obtain it by calling the API for getting enterprise authorization information.
userid_listStringNouser123,user456The list of recipient user IDs. The maximum length is 100.
dept_id_listStringNo123,345The list of recipient department IDs. The maximum length is 20. When the recipient is a department ID, all users in its sub-departments are included.
to_all_userBooleanNofalseWhether to send the message to all users in your organization. Note When set to false, you must specify the value of either userid_list or dept_id_list.
msgJSON ObjectYes{"msgtype":"text","text":{"content":"Please submit the daily report."}}The message content, with a maximum length of 2,048 bytes. The following message notification types are supported. Available msgtype values: Important Multiple message types cannot be sent in a single call. - text: Text message - image: Image message - voice: Voice message - file: File message - link: Link message - oa: OA message Note An OA message supports setting the message status text and color through the status_bar parameter. After sending, you can update the message status and color by calling the Update Work Notification status bar API. - markdown: Markdown message - action_card: Card message

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=7e0a4xxxx31351' \
-d 'agent_id=123' \
-d 'dept_id_list=123%2C456' \
-d 'msg=%7B+++%5C%22msgtype%5C%22%3A+%5C%22text%5C%22%2C+%5C%22text%5C%22%3A+%7B+++++%5C%22content%5C%22%3A+%5C%22Leave+request+from+John%5C%22+++%7D+%7D' \
-d 'to_all_user=false' \
-d 'userid_list=123%2C456'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/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());
Python 
import dingtalk.api

req=dingtalk.api.OapiMessageCorpconversationAsyncsendV2Request("https://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2")

req.agent_id=123
req.userid_list="123,456"
req.dept_id_list="123,456"
req.to_all_user=false
req.msg="{\"msgtype\":\"text\",\"text\": {\"content\": \"Leave request from John\"}}"
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 OapiMessageCorpconversationAsyncsendV2Request;
$req->setAgentId("123");
$req->setUseridList("123,456");
$req->setDeptIdList("123,456");
$req->setToAllUser("false");
$msg = new Msg;
$msg->msgtype="text";
$text = new Text;
$text->content="123";
$msg->text = $text;
$req->setMsg($msg);
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2");
OapiMessageCorpconversationAsyncsendV2Request req = new OapiMessageCorpconversationAsyncsendV2Request();
req.AgentId = 123L;
req.UseridList = "123,456";
req.DeptIdList = "123,456";
req.ToAllUser = false;
OapiMessageCorpconversationAsyncsendV2Request.MsgDomain obj1 = new OapiMessageCorpconversationAsyncsendV2Request.MsgDomain();
obj1.Msgtype = "text";
OapiMessageCorpconversationAsyncsendV2Request.TextDomain obj2 = new OapiMessageCorpconversationAsyncsendV2Request.TextDomain();
obj2.Content = "123";
obj1.Text= obj2;
req.Msg_ = obj1;
OapiMessageCorpconversationAsyncsendV2Response rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
request_idString4jzllmte0wauThe request ID.
errmsgStringokThe description of the return code. Important If the API call succeeds but the recipient does not receive the message, call Get the result of sending messages asynchronously to the enterprise to query the result and compare it with the error codes listed in the documentation.
errcodeNumber0The return code.
task_idNumber256271667526The ID of the created asynchronous send task.

​
Response body example

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

​
Error codes

If an error is returned when you call this API, look up the solution in the Global error codes documentation based on the error message.