钉钉机器人接口

简介:钉钉机器人接口

HOST:http://localhost:10101

联系人:

Version:1.0

接口路径:/v3/api-docs

[TOC]

认证鉴权

接口安全通过鉴权进行保障，能力调用鉴权采用如下方式：

对调用方的身份鉴权。每个接入平台的应用都需要在平台进行注册，注册完成后平台分配给应用APP_ID和APP_SECRET；
平台提供TOKEN算法。应用的请求中必须在请求头加上APP_ID、TIMESTAMP、TRACE_ID和TOKEN参数，用于应用的身份验证。TOKEN算法如下：

TOKEN原始内容为json字符串，使用AES/ECB/PKCS5Padding加密算法和APP_SECRET进行加密，最后将加密内容转成base64，TOKEN需包含以下参数：

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	当前的系统时间戳，单位为毫秒，格式为“yyyy-MM-dd HH:mm:ss.SSS”；例如："2018-05-10 15:05:58.174"
TRACE_ID	序列号，根据上述时间戳和随机数生成，生成的长度为23的字符串，格式为：yyyyMMddhhmmssSSS+6位随机数。例如：“20180510150558174549793”

TOKEN原始内容json字符串示例：

{"APP_ID":"APP_ID","TIMESTAMP":"2018-05-10 15:05:58.174","TRACE_ID":"20180510150558174549793"}

加密TOKEN代码示例：

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.KeyGenerator;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;

/**
 * 加密解密工具
 */
@Slf4j
public class AesUtil {
    /**
     * 加密算法
     */
    private static final String ALGORITHM = "AES";
    /**
     * 加密算法填充方式
     */
    private static final String TRANSFORMATION = ALGORITHM + "/ECB/PKCS5Padding";

    public static void main(String[] args) {
        try {
            // 应用编码
            String appId = "";
            // 应用密钥
            String appSecret = "";
            // 生成token
            String token = generateToken(appId, appSecret);
            System.out.println(token);
        } catch (Exception e) {
            log.error(e.toString(), e);
        }
    }

    /**
     * 加密
     * @param text 内容
     * @param key 密钥
     */
    public static String encrypt(String text, String key) throws NoSuchPaddingException, NoSuchAlgorithmException,
            IllegalBlockSizeException, BadPaddingException, InvalidKeyException {
        // 获取Cipher实例并设置为加密模式
        Cipher cipher = Cipher.getInstance(TRANSFORMATION);
        cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(Base64.getDecoder().decode(key), ALGORITHM));
        // 执行加密操作并返回Base64编码的字符串
        return Base64.getEncoder().encodeToString(cipher.doFinal(text.getBytes()));
    }

    /**
     * 解密
     * @param text 加密内容
     * @param key 密钥
     */
    public static String decrypt(String text, String key) throws NoSuchPaddingException, NoSuchAlgorithmException,
            InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
        // 获取Cipher实例并设置为解密模式
        Cipher cipher = Cipher.getInstance(TRANSFORMATION);
        cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(Base64.getDecoder().decode(key), ALGORITHM));
        // 解码Base64字符串并执行解密操作
        return new String(cipher.doFinal(Base64.getDecoder().decode(text)));
    }

    /**
     * 生成token
     * @param appId 应用编码
     * @param appSecret 应用密钥
     */
    public static String generateToken(String appId, String appSecret) throws JsonProcessingException,
            NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException,
            InvalidKeyException {
        // 获取当前时间
        LocalDateTime now = LocalDateTime.now();
        // 格式化时间戳
        String timestamp = now.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS"));
        // 生成追踪ID
        String traceId = generateTraceId(now);
        // 创建对象映射器用于处理JSON
        ObjectMapper objectMapper = new ObjectMapper();
        // 创建Map存储需要加密的信息
        Map<String, String> m = new HashMap<>();
        m.put("APP_ID", appId);
        m.put("TIMESTAMP", timestamp);
        m.put("TRACE_ID", traceId);
        // 将Map转换为JSON字符串并进行加密
        String s = objectMapper.writeValueAsString(m);
        return encrypt(s, appSecret);
    }

    /**
     * 生成traceId
     * @param time 时间
     */
    public static String generateTraceId(LocalDateTime time) {
        return time.format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"))
                + ThreadLocalRandom.current().nextInt(100000, 1000000);
    }
}

应用机器人操作命令接口规范

用户向机器人发送操作命令，机器人收到操作命令，本系统将操作命令转发给相关应用接口，具体的后续操作由相关应用自行定义，应用接口需符合以下规范：

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "senderStaffId": "xxxx",
  "conversationType": "1",
  "conversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "parameter": "202401"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型
APP_ID	应用编码	header	true
TIMESTAMP	当前的系统时间戳，单位为毫秒，格式为“yyyy-MM-dd HH:mm:ss.SSS”；例如："2018-05-10 15:05:58.174"	header	true
TRACE_ID	序列号，根据上述时间戳和随机数生成，生成的长度为23的字符串，格式为：yyyyMMddhhmmssSSS+6位随机数。例如：“20180510150558174549793”	header	true
TOKEN	访问令牌	header	true
dto		body	true
robotCode	机器人的编码		true	string
senderStaffId	企业内部群中@该机器人的用户ID		true	string
conversationType	会话类型：1：单聊，2：群聊		true	string
conversationId	会话ID		true	string
parameter	参数		true	string

响应状态:

状态码	说明	schema
200	OK

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
message	提示信息	string

响应示例:

{
	"success": true,
	"message": "成功",
}

钉钉机器人接口

上传媒体文件

接口地址:/api/open/upload

请求方式:POST

请求数据类型:multipart/form-data

响应数据类型:application/json

接口描述:

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
file	文件，最大20MB	multipart/form-data	true	file
robotCode	机器人的编码 base64	multipart/form-data	true	string

响应状态:

状态码	说明	schema
200	OK	RUploadVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		UploadVo	UploadVo
mediaId	媒体文件上传后获取的唯一标识	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx"
	},
	"traceId": "20231231235959436337954"
}

企业机器人撤回内部群消息

接口地址:/api/open/recallGroupMessages

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "processQueryKeys": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
recallGroupMessagesDto	RecallGroupMessagesDto	body	true	RecallGroupMessagesDto	RecallGroupMessagesDto
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string
processQueryKeys	消息唯一标识列表，每次最多传20个，在发送消息24小时内可以通过processQueryKey撤回消息，超过24小时则无法撤回消息		true	array	string

响应状态:

状态码	说明	schema
200	OK	RRecallGroupMessagesVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		RecallGroupMessagesVo	RecallGroupMessagesVo
successResult	撤回成功的消息发送任务ID列表	array	string
failedResult	撤回失败的消息发送任务ID列表及对应的失败原因	object
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"successResult": [],
		"failedResult": {}
	},
	"traceId": "20231231235959436337954"
}

机器人发送群聊文本类型消息

接口地址:/api/open/groupSendSampleText

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "content": "content",
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx=="
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
groupSendSampleTextDto	GroupSendSampleTextDto	body	true	GroupSendSampleTextDto	GroupSendSampleTextDto
content	内容		true	string
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人发送群聊Markdown类型消息

接口地址:/api/open/groupSendSampleMarkdown

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "title": "title",
  "text": "text",
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx=="
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
groupSendSampleMarkdownDto	GroupSendSampleMarkdownDto	body	true	GroupSendSampleMarkdownDto	GroupSendSampleMarkdownDto
title	标题		true	string
text	内容		true	string
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人发送群聊图片类型消息

接口地址:/api/open/groupSendSampleImageMsg

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
groupSendSampleImageMsgDto	GroupSendSampleImageMsgDto	body	true	GroupSendSampleImageMsgDto	GroupSendSampleImageMsgDto
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string
mediaId	媒体文件上传后获取的唯一标识		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人发送群聊文件类型消息

接口地址:/api/open/groupSendSampleFile

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx",
  "filename": "a.xlsx"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
groupSendSampleFileDto	GroupSendSampleFileDto	body	true	GroupSendSampleFileDto	GroupSendSampleFileDto
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string
mediaId	媒体文件上传后获取的唯一标识		true	string
filename	文件名		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

根据手机号获取用户的userId

接口地址:/api/open/getUserIdByMobile

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "mobile": "12345678901"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
getUserIdByMobileDto	GetUserIdByMobileDto	body	true	GetUserIdByMobileDto	GetUserIdByMobileDto
robotCode	机器人的编码		true	string
mobile	用户的手机号		true	string

响应状态:

状态码	说明	schema
200	OK	RGetUserIdByMobileVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GetUserIdByMobileVo	GetUserIdByMobileVo
userId	员工的userId	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"userId": "xxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人批量发送文本类型消息

接口地址:/api/open/batchSendOtoSampleText

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "content": "content",
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "phones": [],
  "userIds": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
batchSendSampleTextDto	BatchSendSampleTextDto	body	true	BatchSendSampleTextDto	BatchSendSampleTextDto
content	内容		true	string
robotCode	机器人的编码		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		true	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		true	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

机器人批量发送Markdown类型消息

接口地址:/api/open/batchSendOtoSampleMarkdown

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "title": "title",
  "text": "content",
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "phones": [],
  "userIds": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
batchSendSampleMarkdownDto	BatchSendSampleMarkdownDto	body	true	BatchSendSampleMarkdownDto	BatchSendSampleMarkdownDto
title	标题		true	string
text	内容		true	string
robotCode	机器人的编码		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		true	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		true	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

机器人批量发送图片类型消息

接口地址:/api/open/batchSendOtoSampleImageMsg

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx",
  "phones": [],
  "userIds": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
batchSendOtoSampleImageMsgDto	BatchSendOtoSampleImageMsgDto	body	true	BatchSendOtoSampleImageMsgDto	BatchSendOtoSampleImageMsgDto
robotCode	机器人的编码		true	string
mediaId	媒体文件上传后获取的唯一标识		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		false	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		false	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

机器人批量发送文件类型消息

接口地址:/api/open/batchSendOtoSampleFile

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx",
  "phones": [],
  "userIds": [],
  "filename": "a.xlsx"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
batchSendOtoSampleFileDto	BatchSendOtoSampleFileDto	body	true	BatchSendOtoSampleFileDto	BatchSendOtoSampleFileDto
robotCode	机器人的编码		true	string
mediaId	媒体文件上传后获取的唯一标识		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		false	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		false	array	string
filename	文件名		true	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

批量撤回人与机器人会话中机器人消息

接口地址:/api/open/batchRecallOtoMessages

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "processQueryKeys": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
batchRecallOtoMessagesDto	BatchRecallOtoMessagesDto	body	true	BatchRecallOtoMessagesDto	BatchRecallOtoMessagesDto
robotCode	机器人的编码		true	string
processQueryKeys	消息唯一标识列表，每次最多传20个，在发送消息24小时内可以通过processQueryKey撤回消息，超过24小时则无法撤回消息		true	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchRecallOtoMessagesVo

响应头:

参数名称	参数说明
APP_ID	应用编码
TIMESTAMP	时间戳
TRACE_ID	序列号

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchRecallOtoMessagesVo	BatchRecallOtoMessagesVo
successResult	撤回成功的消息发送任务ID列表	array	string
failedResult	撤回失败的消息发送任务ID列表及对应的失败原因	object
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"successResult": [],
		"failedResult": {}
	},
	"traceId": "20231231235959436337954"
}

机器人通过sftp下载图片并发送群聊图片类型消息

接口地址:/api/open/sftpGroupSendSampleImageMsg

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "sftpId": "xxxx",
  "filePath": "/data/a.png"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
sftpGroupSendSampleImageMsgDto	SftpGroupSendSampleImageMsgDto	body	true	SftpGroupSendSampleImageMsgDto	SftpGroupSendSampleImageMsgDto
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string
sftpId	sftp id		true	string
filePath	图片绝对路径		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人通过sftp下载文件并发送群聊文件类型消息

接口地址:/api/open/sftpGroupSendSampleFile

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "openConversationId": "cid6KeBBLoveMJOGXoYKF5x7Eeixxxx==",
  "sftpId": "xxxx",
  "filePath": "/data/a.pdf"
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
sftpGroupSendSampleFileDto	SftpGroupSendSampleFileDto	body	true	SftpGroupSendSampleFileDto	SftpGroupSendSampleFileDto
robotCode	机器人的编码		true	string
openConversationId	会话ID		true	string
sftpId	sftp id		true	string
filePath	文件绝对路径		true	string

响应状态:

状态码	说明	schema
200	OK	RGroupSendVo

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		GroupSendVo	GroupSendVo
processQueryKey	加密消息id，根据此id可查询消息已读状态和撤回消息	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}

机器人通过sftp下载图片并批量发送图片类型消息

接口地址:/api/open/sftpBatchSendOtoSampleImageMsg

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "sftpId": "xxxx",
  "filePath": "/data/a.png",
  "phones": [],
  "userIds": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
sftpBatchSendOtoSampleImageMsgDto	SftpBatchSendOtoSampleImageMsgDto	body	true	SftpBatchSendOtoSampleImageMsgDto	SftpBatchSendOtoSampleImageMsgDto
robotCode	机器人的编码		true	string
sftpId	sftp id		true	string
filePath	图片绝对路径		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		false	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		false	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

机器人通过sftp下载文件并批量发送文件类型消息

接口地址:/api/open/sftpBatchSendOtoSampleFile

请求方式:POST

请求数据类型:application/json

响应数据类型:application/json

接口描述:

请求示例:

{
  "robotCode": "dingue4kfzdxbynxxxxxx",
  "sftpId": "xxxx",
  "filePath": "/data/a.pdf",
  "phones": [],
  "userIds": []
}

请求参数:

参数名称	参数说明	请求类型	是否必须	数据类型	schema
APP_ID	应用编码	header	true
TIMESTAMP	时间戳	header	true
TRACE_ID	序列号	header	true
TOKEN	访问令牌	header	true
sftpBatchSendOtoSampleFileDto	SftpBatchSendOtoSampleFileDto	body	true	SftpBatchSendOtoSampleFileDto	SftpBatchSendOtoSampleFileDto
robotCode	机器人的编码		true	string
sftpId	sftp id		true	string
filePath	文件绝对路径		true	string
phones	接收机器人消息的用户的手机号列表，每次最多传20个		false	array	string
userIds	接收机器人消息的用户的userId列表，每次最多传20个		false	array	string

响应状态:

状态码	说明	schema
200	OK	RBatchSendVo

响应参数:

参数名称	参数说明	类型	schema
success	是否成功	boolean
code	错误码	integer(int32)	integer(int32)
message	提示信息	string
data		BatchSendVo	BatchSendVo
processQueryKey	消息id，根据此id，可用于查询消息是否已读和撤回消息	string
failPhones	失败的手机号列表和对应原因	object
invalidStaffIdList	无效的用户userId列表	array	string
flowControlledStaffIdList	被限流的userId列表	array	string
traceId	请求跟踪id	string

响应示例:

{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}

钉钉机器人接口.md 39 KB 履歴 Raw

钉钉机器人接口

认证鉴权

应用机器人操作命令接口规范

钉钉机器人接口

上传媒体文件

企业机器人撤回内部群消息

机器人发送群聊文本类型消息

机器人发送群聊Markdown类型消息

机器人发送群聊图片类型消息

机器人发送群聊文件类型消息

根据手机号获取用户的userId

机器人批量发送文本类型消息

机器人批量发送Markdown类型消息

机器人批量发送图片类型消息

机器人批量发送文件类型消息

批量撤回人与机器人会话中机器人消息

机器人通过sftp下载图片并发送群聊图片类型消息

机器人通过sftp下载文件并发送群聊文件类型消息

机器人通过sftp下载图片并批量发送图片类型消息

机器人通过sftp下载文件并批量发送文件类型消息

钉钉机器人接口.md 39 KB

履歴 Raw