Developer GuideAPI call description
This API is suitable for scenarios where you need to confirm whether a Work Notification message has been successfully delivered to specific users. For example, after the HR department of an organization sends an important notification, you may need to confirm whether employees have received it.Notes
- This API only returns the delivery result of Work Notification messages sent within the last 24 hours.
- This API does not support recipient lists that exceed 100 users. Otherwise, the system returns Call timeout.
Request
| Basic information | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/message/corpconversation/getsendresult |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Required permissions | permission-qyapi_base-Basic permission required to call enterprise APIs |
Query parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| access_token | String | Yes | bE74xxxx | The app credential for calling 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
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| agent_id | Number | Yes | 836390886 | The 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. image - For a third-party enterprise app, obtain it by calling the API for getting enterprise authorization information. |
| task_id | Number | Yes | 256271667526 | The task ID returned by DingTalk when the message was sent. Call the Send Work Notification API to obtain the value of task_id. Note Only tasks created within the last 24 hours can be queried. |
Request example
curl -X POST "https://api.dingtalk.io/topapi/message/corpconversation/getsendresult" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=cfe36xxxxd8dbce' \
-d 'agent_id=123' \
-d 'task_id=456'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/message/corpconversation/getsendresult");
OapiMessageCorpconversationGetsendresultRequest req = new OapiMessageCorpconversationGetsendresultRequest();
req.setAgentId(123L);
req.setTaskId(456L);
OapiMessageCorpconversationGetsendresultResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiMessageCorpconversationGetsendresultRequest("https://api.dingtalk.io/topapi/message/corpconversation/getsendresult")
req.agent_id=123
req.task_id=456
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiMessageCorpconversationGetsendresultRequest;
$req->setAgentId("123");
$req->setTaskId("456");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/message/corpconversation/getsendresult");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/message/corpconversation/getsendresult");
OapiMessageCorpconversationGetsendresultRequest req = new OapiMessageCorpconversationGetsendresultRequest();
req.AgentId = 123L;
req.TaskId = 456L;
OapiMessageCorpconversationGetsendresultResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Response
Response body
| Name | Type | Example | Description |
|---|---|---|---|
| send_result | AsyncSendResult | The returned result. | |
| invalid_user_id_list | String[] | [“manager4220”,user123”] | Invalid user IDs. |
| forbidden_user_id_list | String[] | [“manager4220”,user123”] | The user IDs that were not actually sent due to rate limiting caused by sending messages too frequently or in excessive volume. Recipients not affected by the rate limit are still sent successfully. Rate limit rules include: - Sending the same content to the same user is allowed only once per day. - For the same app sending messages to the same user: - For third-party enterprise apps, the daily limit is 100 messages per user. - For internal apps, the daily limit is 500 messages per user. |
| failed_user_id_list | String[] | [“manager4220”,user123”] | The user IDs that failed to receive the message. |
| read_user_id_list | String[] | [“manager4220”,user123”] | The user IDs that have read the message. |
| unread_user_id_list | String[] | [“manager4220”,user123”] | The user IDs that have not read the message. |
| invalid_dept_id_list | Number[] | [1,2,3] | Invalid department IDs. |
| forbidden_list | SendForbiddenModel[] | The specific reasons why the push was forbidden. | |
| code | String | 143105 | The rate limit code. - 143105 indicates that the daily limit of messages pushed to a user by an internal app has been exceeded. - 143106 indicates that an internal app has sent duplicate messages to a user. |
| count | Number | 1 | The rate limit threshold. |
| userid | String | user123 | The user ID of the employee affected by the rate limit. |
| errcode | Number | 0 | The return code. |
| errmsg | String | ok | The description of the return code. |
| request_id | String | 6pcvwp6jcows | The request ID. |
Response example
{
"errcode": 0,
"send_result": {
"failed_user_id_list": [],
"forbidden_list": [],
"invalid_dept_id_list": [],
"invalid_user_id_list": [],
"read_user_id_list": [
"manager4220"
],
"unread_user_id_list": []
},
"request_id": "6pcvwp6jcows"
}
Error codes
If an error occurs when calling this API, refer to the Global error codes document and find the solution based on the error message.| Error code | Description | Solution |
|---|---|---|
| 143103 | The QPM limit for the number of message recipients per app within the organization has been exceeded. | The API is being called too frequently. Try again later. |
| 143104 | The QPM limit for the number of message recipients per minute within the organization has been exceeded. | The API is being called too frequently. Try again later. |
| 143105 | The daily push limit per user per app has been exceeded. | An organization can send up to 500 message notifications per employee per day, while an ISV can send up to 50. |
| 143106 | The limit for duplicate messages pushed by a single app to a single user has been exceeded. | Only one message notification with the same content can be sent to the same employee per day. |
| 143203 | The QPM limit for an ISV app sending to a single organization has been exceeded. | The API is being called too frequently. Try again later. |
| 143204 | The QPM limit for an ISV app sending to all organizations has been exceeded. | The API is being called too frequently. Try again later. |
| 143205 | The daily push limit per user per app has been exceeded. | An organization can send up to 500 message notifications per employee per day, while an ISV can send up to 50. |
| 143206 | The limit for duplicate messages pushed by a single app to a single user has been exceeded. | Only one message notification with the same content can be sent to the same employee per day. |
| 1430000 | The recipient is empty. | The recipient cannot be empty. Check whether the message recipient is empty. |
| 1430001 | Unrecognized grantType. | None. |
| 1430002 | The message contains prohibited content. | Check whether the message text contains pornographic, reactionary, or other prohibited words. |
| 1430003 | OAPI system protection triggered. | None. |
| 1430004 | Senior executive protection. | Disable senior executive protection. |