需求：在业务系统中产生的通知消息，通过调用钉钉服务端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上传消息中使用的媒体文件
钉钉上传媒体文件