java 钉钉发送消息通知带按钮 钉钉发消息api

需求：在业务系统中产生的通知消息，通过调用钉钉服务端API，发送到对应员工的钉钉客户端。

---

步骤：

目录

1.创建并配置消息发送应用

1.1登录开发者后台

1.2创建H5微应用

1.3配置H5微应用

2.调用服务端API发送消息

2.1获取access_token

2.2根据手机号获取userid

2.3发送工作通知消息

2.4查询工作通知消息的发送进度

2.5查询工作通知消息的发送结果

2.6工作通知消息撤回

3.消息类型

3.1消息类型与数据格式

3.2上传消息中使用的媒体文件

---

1.创建并配置消息发送应用

1.1登录开发者后台

       打开钉钉开放平台https://ding-doc.dingtalk.com/，点右上角的“登录开发者后台”，然后使用企业管理者帐户登陆。

1.2创建H5微应用

       选择"应用开发"->"企业内部开发"->"H5微应用"，点击"创建应用"，开始创建企业自建微应用。

          填写应用基本信息。包括应用名称、应用Logo和应用简介，选择"企业内部自主开发"，点击"下一步"。

      开发模式选择“开发应用”，开发应用类型选择“微应用”，应用首页链接填写H5微应用首页url，服务器出口IP填写本企业服务器的公网IP。点击创建。

1.3配置H5微应用

      查看创建好的应用信息，取得AgentId、AppKey和AppSecret，在API调用时要使用。

      在人员设置页设置使用该应用的人员，其他人员接收不到通知消息。

      在接口权限页面，高级权限-企业通讯录权限部分，申请打开[通讯录只读权限]和[手机号获取userid],并且可以设定该权限的范围是对全体员工还是部分员工

2.调用服务端API发送消息

2.1获取access_token

       【注意】正常情况下access_token有效期为7200秒，有效期内重复获取返回相同结果，并自动续期。

         调试工具：在线调试

         请求方式：GET（HTTPS）

         请求地址：https://oapi.dingtalk.com/gettoken?appkey=key&appsecret=secret

         参数说明：

参数	参数类型	必须	说明
appkey	String	是	应用的唯一标识key
appsecret	String	是	应用的密钥

       SDK请求示例（JAVA）：

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/gettoken");
OapiGettokenRequest request = new OapiGettokenRequest();
request.setAppkey("appkey");
request.setAppsecret("appsecret");
request.setHttpMethod("GET");
OapiGettokenResponse response = client.execute(request);

       返回说明：

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

2.2根据手机号获取userid

          企业使用此接口可通过手机号获取其所对应员工的userid。

          调试工具：在线调试

          请求方式：GET（HTTPS）

          请求地址：https://oapi.dingtalk.com/user/get_by_mobile?access_token=ACCESS_TOKEN&mobile=1xxxxxxxxxx

          参数说明：

名称	类型	是否必须	说明
access_token	String	必须	调用接口凭证，通过获取企业access_token获取
mobile	String	必须	手机号码

          SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get_by_mobile");
OapiUserGetByMobileRequest request = new OapiUserGetByMobileRequest();
request.setMobile("1xxxxxxxxxx");
OapiUserGetByMobileResponse execute = client.execute(request, access_token);

          返回结果：

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

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	员工在当前企业内的唯一标识。

2.3发送工作通知消息

         发送工作通知消息需要注意以下事项：

• 同一个微应用相同消息的内容同一个用户一天只能接收一次。
• 同一个微应用给同一个用户发送消息，企业内部开发方式一天不得超过500次。
• 通过设置to_all_user参数全员推送消息，一天最多3次。
• 详细的限制说明，请参考“工作通知消息的限制”。
• 该接口是异步发送消息，接口返回成功并不表示用户一定会收到消息，需要通过“查询工作通知消息的发送结果”接口查询是否给用户发送成功。
• 消息类型和样例可参考消息类型文档。

         调试工具：在线调试

         请求方式：POST（HTTPS）

         请求地址：https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=ACCESS_TOKEN

         参数说明：

名称	类型	是否必须	示例值	说明
agent_id	Number	必须	1234	应用agentId
userid_list	String	可选(userid_list,dept_id_list, to_all_user必须有一个不能为空)	zhangsan,lisi	接收者的用户userid列表，最大列表长度：100
dept_id_list	String	可选（可不传，若传不能为空）	123,456	接收者的部门id列表，最大列表长度：20,  接收者是部门id下(包括子部门下)的所有用户
to_all_user	Boolean	可选	false	是否发送给企业全部用户
msg	json对象	必须	{"msgtype":"text","text":{"content":"消息内容"}}	消息内容，消息类型和样例参考“消息类型与数据格式”。最长不超过2048个字节

         SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2");

OapiMessageCorpconversationAsyncsendV2Request request = new OapiMessageCorpconversationAsyncsendV2Request();
request.setUseridList("01376814877479");
request.setAgentId(153858650L);
request.setToAllUser(false);

OapiMessageCorpconversationAsyncsendV2Request.Msg msg = new OapiMessageCorpconversationAsyncsendV2Request.Msg();
msg.setMsgtype("text");
msg.setText(new OapiMessageCorpconversationAsyncsendV2Request.Text());
msg.getText().setContent("test123");
request.setMsg(msg);

msg.setMsgtype("image");
msg.setImage(new OapiMessageCorpconversationAsyncsendV2Request.Image());
msg.getImage().setMediaId("@lADOdvRYes0CbM0CbA");
request.setMsg(msg);

msg.setMsgtype("file");
msg.setFile(new OapiMessageCorpconversationAsyncsendV2Request.File());
msg.getFile().setMediaId("@lADOdvRYes0CbM0CbA");
request.setMsg(msg);

msg.setMsgtype("link");
msg.setLink(new OapiMessageCorpconversationAsyncsendV2Request.Link());
msg.getLink().setTitle("test");
msg.getLink().setText("test");
msg.getLink().setMessageUrl("test");
msg.getLink().setPicUrl("test");
request.setMsg(msg);

msg.setMsgtype("markdown");
msg.setMarkdown(new OapiMessageCorpconversationAsyncsendV2Request.Markdown());
msg.getMarkdown().setText("##### text");
msg.getMarkdown().setTitle("### Title");
request.setMsg(msg);

msg.setOa(new OapiMessageCorpconversationAsyncsendV2Request.OA());
msg.getOa().setHead(new OapiMessageCorpconversationAsyncsendV2Request.Head());
msg.getOa().getHead().setText("head");
msg.getOa().setBody(new OapiMessageCorpconversationAsyncsendV2Request.Body());
msg.getOa().getBody().setContent("xxx");
msg.setMsgtype("oa");
request.setMsg(msg);

msg.setActionCard(new OapiMessageCorpconversationAsyncsendV2Request.ActionCard());
msg.getActionCard().setTitle("xxx123411111");
msg.getActionCard().setMarkdown("### 测试123111");
msg.getActionCard().setSingleTitle("测试测试");
msg.getActionCard().setSingleUrl("https://www.baidu.com");
msg.setMsgtype("action_card");
request.setMsg(msg);

OapiMessageCorpconversationAsyncsendV2Response response = client.execute(request,accessToken);

         返回结果：

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

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
task_id	创建的发送任务id

2.4查询工作通知消息的发送进度

         调试工具：在线调试

         请求方式：POST（HTTPS）

         请求地址：https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress?access_token=ACCESS_TOKEN

         参数说明：

名称	类型	是否必须	示例值	说明
agent_id	Number	必须	123	发送消息时使用的微应用的id
task_id	Number	必须	456	发送消息时钉钉返回的任务id

         SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress");
OapiMessageCorpconversationGetsendprogressRequest request  = new OapiMessageCorpconversationGetsendprogressRequest();
request.setAgentId(135717601L);
request.setTaskId(9326688016L);
OapiMessageCorpconversationGetsendprogressResponse response = client.execute(request, accessToken);

         返回结果：

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

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
progress
└ progress_in_percent	取值 0-100，表示处理的百分比
└ status	任务执行状态，0=未开始，1=处理中，2=处理完毕

2.5查询工作通知消息的发送结果

         调试工具：在线调试

         请求方式：POST（HTTPS）

         请求地址：https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult?access_token=ACCESS_TOKEN

         参数说明：

名称	类型	是否必须	示例值	说明
agent_id	Number	可选	123	微应用的agentid
task_id	Number	可选	456	异步任务的id

         SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult");
OapiMessageCorpconversationGetsendresultRequest request  = new OapiMessageCorpconversationGetsendresultRequest();
request.setAgentId(135717601L);
request.setTaskId(9326688016L);
OapiMessageCorpconversationGetsendresultResponse response = client.execute(request, accessToken);

         返回结果：

{
    "send_result":{
        "invalid_user_id_list":"zhangsan,lisi",
        "forbidden_user_id_list":"zhangsan,lisi",
        "failed_user_id_list":"zhangsan,lisi",
        "read_user_id_list":"zhangsan,lisi",
        "unread_user_id_list":"zhangsan,lisi",
        "invalid_dept_id_list":"1,2,3"
    },
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
send_result
└ invalid_user_id_list	无效的用户id
└ forbidden_user_id_list	因发送消息超过上限而被流控过滤后实际未发送的userid。未被限流的接收者仍会被收到消息。 限流规则包括： 1、同一个微应用相同消息的内容同一个用户一天只能接收一次。 2、同一个微应用给同一个用户发送消息，如果是ISV应用开发方式一天不得超过50次；如果是企业内部开发方式，此上限为500次。
└ failed_user_id_list	发送失败的用户id
└ read_user_id_list	已读消息的用户id
└ unread_user_id_list	未读消息的用户id
└ invalid_dept_id_list	无效的部门id

2.6工作通知消息撤回

         调试工具：在线调试

         请求方式：POST（HTTPS）

         请求地址：https://oapi.dingtalk.com/topapi/message/corpconversation/recall?access_token=ACCESS_TOKEN

         参数说明：

名称	类型	是否必须	示例值	说明
agent_id	Number	可选	123	微应用的agentid
msg_task_id	Number	可选	456	异步任务的id

         SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/message/corpconversation/recall");
OapiMessageCorpconversationRecallRequest request = new OapiMessageCorpconversationRecallRequest();
request.setAgentId(237990693L);
request.setMsgTaskId(3568141183L);
OapiMessageCorpconversationRecallResponse response = client.execute(request, accessToken);

         返回结果：

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

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容

3.消息类型

3.1消息类型与数据格式

       钉钉消息类型与数据格式说明

3.2上传消息中使用的媒体文件

       钉钉上传媒体文件