Skip to main content
This topic describes how to call the APIs related to Work Notifications to send, query, and recall messages.

​
Expected result

The following figure shows the result of sending a Work Notification.

​
Integration flow overview

This document walks through the process of creating an internal app and using the attendance-related APIs to send Work Notifications. Prerequisites: Complete the App creation and configuration flow. Step 1: Obtain the app credential, including the client ID and Client Secret. Step 2: Apply for API permissions for the Work Notification APIs. Step 3: Obtain the access credential (access_token) of the internal app. The access token is used to authenticate the caller when calling APIs. Step 4: Call the Work Notification APIs:
  1. Call the Server API Send a Work Notification to send a Work Notification and obtain the unique task ID task_id of the message.
  2. With the unique task ID task_id, call the Server API Get the sending progress of a Work Notification to query the sending progress.
  3. With the unique task ID task_id, call the Server API Get the sending result of a Work Notification to view the sending result.
  4. With the unique task ID task_id, call the Server API Update the status bar of a Work Notification to update the Work Notification.
  5. With the unique task ID task_id, call the Server API Recall a Work Notification to recall the Work Notification.

​
Prerequisites

Complete the App creation and configuration flow.

​
Step 1: Obtain the app credential

  1. Select the target app to open the app details page, and click Basic information > Credentials and basic information.
  2. Obtain the client ID and Client Secret.

​
Step 2: Add API permissions

The API permissions are enabled by default. No application is required.

​
Step 3: Obtain the access token of the app

For details about the differences between Server API versions, see the comparison between the legacy API and the new API. The following APIs are all Server APIs. For details about how to download the SDK, see Server-side SDK download.
Use the client ID and Client Secret obtained in Step 1 to obtain the access_token of the internal app. 
public void getAccessToken() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
        OapiGettokenRequest req = new OapiGettokenRequest();
        req.setAppkey("dingxxxxxxxxxhgn");
        req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
        req.setHttpMethod("GET");
        OapiGettokenResponse rsp = client.execute(req);
        System.out.println(rsp.getBody());
}
  1. Call the Server API Send a Work Notification to send a Work Notification and obtain the unique task ID task_id of the message.
public void OAWorkNotice() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/asyncsend_v2");
        OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
        request.setAgentId(1185599675L);
        request.setUseridList("manager7675");
        request.setToAllUser(false);

        OapiMessageCorpconversationAsyncsendV2Request.Msg msg = new OapiMessageCorpconversationAsyncsendV2Request.Msg();
        OapiMessageCorpconversationAsyncsendV2Request.OA oa = new OapiMessageCorpconversationAsyncsendV2Request.OA();

        OapiMessageCorpconversationAsyncsendV2Request.Head head = new OapiMessageCorpconversationAsyncsendV2Request.Head();
        head.setBgcolor("FFFF6A00");
        head.setText("Test");
        OapiMessageCorpconversationAsyncsendV2Request.Body body = new OapiMessageCorpconversationAsyncsendV2Request.Body();
        List<OapiMessageCorpconversationAsyncsendV2Request.Form> list = new ArrayList<>();
        OapiMessageCorpconversationAsyncsendV2Request.Form form1 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form1.setKey("Name:");
        form1.setValue("John");
        OapiMessageCorpconversationAsyncsendV2Request.Form form2 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form2.setKey("Age:");
        form2.setValue("21");
        OapiMessageCorpconversationAsyncsendV2Request.Form form3 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form3.setKey("Height:");
        form3.setValue("1.8 m");
        OapiMessageCorpconversationAsyncsendV2Request.Form form4 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form4.setKey("Weight:");
        form4.setValue("65 kg");
        OapiMessageCorpconversationAsyncsendV2Request.Form form5 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form5.setKey("Education:");
        form5.setValue("Bachelor's degree");
        OapiMessageCorpconversationAsyncsendV2Request.Form form6 = new OapiMessageCorpconversationAsyncsendV2Request.Form();
        form6.setKey("Hobbies:");
        form6.setValue("Sports, listening to music");

        OapiMessageCorpconversationAsyncsendV2Request.Rich rich = new OapiMessageCorpconversationAsyncsendV2Request.Rich();
        rich.setNum("10.6");
        rich.setUnit("USD");

        list.add(form1);
        list.add(form2);
        list.add(form3);
        list.add(form4);
        list.add(form5);
        list.add(form6);

        body.setForm(list);
        body.setRich(rich);
        body.setTitle("Body title 5");
        body.setImage("@lADOADmaWMzazQKA");
        body.setFileCount("3");
        body.setAuthor("Jane");

        OapiMessageCorpconversationAsyncsendV2Request.StatusBar statusBar = new OapiMessageCorpconversationAsyncsendV2Request.StatusBar();
        statusBar.setStatusBg("0xFFFF6A00");
        statusBar.setStatusValue("In progress");

        oa.setMessageUrl("https://dingtalk.io");
        oa.setHead(head);
        oa.setBody(body);
        oa.setStatusBar(statusBar);
        msg.setOa(oa);
        msg.setMsgtype("oa");
        msg.setOa(oa);
        request.setMsg(msg);
        OapiMessageCorpconversationAsyncsendV2Response rsp = client.execute(request, "access_token");
        System.out.println(rsp.getBody());
    }
  1. With the unique task ID task_id, call the Server API Get the sending progress of a Work Notification to query the sending progress.
public void workNoticeSendProgress() throws ApiException {
        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, "access_token");
        System.out.println(rsp.getBody());
    }
  1. With the unique task ID task_id, call the Server API Get the sending result of a Work Notification to view the sending result.
public void workNoticeSendResult() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/getsendresult");
        OapiMessageCorpconversationGetsendresultRequest req = new OapiMessageCorpconversationGetsendresultRequest();
        req.setAgentId(123L);
        req.setTaskId(456L);
        OapiMessageCorpconversationGetsendresultResponse rsp = client.execute(req, "access_token");
        System.out.println(rsp.getBody());
    }
  1. With the unique task ID task_id, call the Server API Update the status bar of a Work Notification to update the Work Notification.
/**
 * Approval status color reference
 * Accepted 0xFF78C06E
 * Declined 0xFFF65E5E
 * Recalled 0xFF858E99
 * Pending approval 0xFFFF9D46
 */
 public void updateWorkNoticeStatus() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/message/corpconversation/status_bar/update");
        OapiMessageCorpconversationStatusBarUpdateRequest request = new OapiMessageCorpconversationStatusBarUpdateRequest();
        request.setAgentId(1068622214L);
        request.setStatusValue("Accepted");
        request.setStatusBg("0xFF78C06E");
        request.setTaskId(313382528774L);
        OapiMessageCorpconversationStatusBarUpdateResponse response = client.execute(request, "access_token");
        System.out.println(JSON.toJSONString(response));
    }
  1. With the unique task ID task_id, call the Server API Recall a Work Notification to recall the Work Notification.
 public void recallWorkNotice() throws ApiException {
        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, "access_token");
        System.out.println(rsp.getBody());
    }