Skip to main content
Call this API to recall a Work Notifications message. This applies to scenarios where an internal app needs to recall a Work Notifications message that was sent by mistake.

​
API call description

You can only recall Work Notifications messages sent within the last 24 hours.

​
Permissions

Server API authorization is granted at the app level. When you create an app, the Message notifications permission is added by default.
App typeSupportedHow to applyAPI Explorer Debug
Internal appSupportedEnabled by default. No application required.Debug
Third-party enterprise appSupportedEnabled by default. No application required.Debug
Third-party personal appNot supported——

​
Basic information

HTTP method: POST Request URL:

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/message/corpconversation/recall
HTTP MethodPOST
Supported app typesappType-Internal app, appType-Third-party enterprise app
Permissions requiredpermission-qyapi_base-Basic permissions required to call enterprise APIs

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe app credential used to call this API. - For an internal app, obtain it by calling the API to get the access_token of an internal app. - For a third-party enterprise app, obtain it by calling the API to get 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, you can find this on the app details page in the Developer Backend. - For a third-party enterprise app, obtain it by calling the API to get enterprise authorization information.
msg_task_idNumberYes256271667526The task ID returned by DingTalk when the message was sent. Call the Send a Work Notification API to obtain the value of the task_id parameter. Note Only Work Notifications messages sent within the last 24 hours can be recalled.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/message/corpconversation/recall" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=404080xxxx4ab30' \
-d 'agent_id=1000' \
-d 'msg_task_id=2000'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/recall");
OapiMessageCorpconversationRecallRequest req = new OapiMessageCorpconversationRecallRequest();
req.setAgentId(1000L);
req.setMsgTaskId(2000L);
OapiMessageCorpconversationRecallResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

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

req.agent_id=1000
req.msg_task_id=2000
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 OapiMessageCorpconversationRecallRequest;
$req->setAgentId("1000");
$req->setMsgTaskId("2000");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/message/corpconversation/recall");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/recall");
OapiMessageCorpconversationRecallRequest req = new OapiMessageCorpconversationRecallRequest();
req.AgentId = 1000L;
req.MsgTaskId = 2000L;
OapiMessageCorpconversationRecallResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
errmsgStringokThe return code description.
errcodeNumber0The return code.

​
Response body example

{
  "errcode":0,
  "errmsg":"ok"
}

​
Error codes

If an error occurs when calling this API, look up the solution in the global error codes document using the error message.
Error code (errorcode)Error message description (errmsg)Solution
400002Invalid agentId or taskIdVerify that agentId and taskId are correct.
500System errorAn unknown system error occurred.