Skip to main content
Call this API to get the delivery progress of work notifications. This is useful when your organization needs to monitor message push status or troubleshoot message delivery errors.

​
API call description

This API only returns the delivery progress of work notifications sent within the past 7 days.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/message/corpconversation/getsendprogress
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Required permissionspermission-qyapi_base-Basic permissions required for calling enterprise APIs

​
Query parameter

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

​
Request body

NameTypeRequiredExampleDescription
agent_idNumberYes836390886The Agent ID of the micro app used to send the message. - For an internal app, view it on the app details page of the Developer Backend. - For a third-party enterprise app, obtain it by calling the API for getting the enterprise authorization information.
task_idNumberYes256271667526The task ID returned by DingTalk when the message was sent. Call the Send work notifications API to get the value of task_id. Note Only tasks created within the past 24 hours can be queried.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/message/corpconversation/getsendprogress" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=a0a25xxxxed3ff' \
-d 'agent_id=123' \
-d 'task_id=456'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/getsendprogress");
OapiMessageCorpconversationGetsendprogressRequest req = new OapiMessageCorpconversationGetsendprogressRequest();
req.setAgentId(123L);
req.setTaskId(456L);
OapiMessageCorpconversationGetsendprogressResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

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

req.agent_id=123
req.task_id=456
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 OapiMessageCorpconversationGetsendprogressRequest;
$req->setAgentId("123");
$req->setTaskId("456");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/message/corpconversation/getsendprogress");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/getsendprogress");
OapiMessageCorpconversationGetsendprogressRequest req = new OapiMessageCorpconversationGetsendprogressRequest();
req.AgentId = 123L;
req.TaskId = 456L;
OapiMessageCorpconversationGetsendprogressResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
request_idString5y2znla8tw3dThe request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
progressAsyncSendProgressThe returned result.
progress_in_percentNumber100The processing percentage. Value range: 0 to 100.
statusNumber2The task execution status: - 0: Not started - 1: In progress - 2: Completed

​
Response example

{
  "errcode": 0,
  "errmsg":"ok",
  "progress": {
    "progress_in_percent": 100,
    "status": 2
  },
  "request_id": "5y2znla8tw3d"
}

​
Error codes

If an error is returned when you call this API, refer to the Global error codes document for solutions based on the error message.
Error code (errorcode)Error message (errmsg)Solution
40035Invalid parameterVerify that task_id or agent_id is correct.
500System errorAn unknown system error occurred.