# 钉钉机器人接口


**简介**:钉钉机器人接口


**HOST**:http://localhost:10101


**联系人**:


**Version**:1.0


**接口路径**:/v3/api-docs


[TOC]

# 认证鉴权

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

1. 对调用方的身份鉴权。每个接入平台的应用都需要在平台进行注册，注册完成后平台分配给应用APP_ID和APP_SECRET；

2. 平台提供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字符串示例：

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

加密TOKEN代码示例：

```java
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`


**请求示例**:


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

**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|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|||
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;senderStaffId|企业内部群中@该机器人的用户ID||true|string||
|conversationType|会话类型：1：单聊，2：群聊||true|string||
|conversationId|会话ID||true|string||
|parameter| 参数                                                         ||true|string||

**响应状态**:


| 状态码 | 说明 | schema |
| ------ | ---- | ------ |
| 200    | OK   |        |

**响应参数**:


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

**响应示例**:

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

# 钉钉机器人接口

## 上传媒体文件


**接口地址**:`/api/open/upload`


**请求方式**:`POST`

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

**响应数据类型**:`application/json`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|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|
|&emsp;&emsp;mediaId|媒体文件上传后获取的唯一标识|string||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"mediaId": "@#lAzPDgCwPn1mJiDOQoLpxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/recallGroupMessages`

**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;openConversationId|会话ID||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;successResult|撤回成功的消息发送任务ID列表|array|string|
|&emsp;&emsp;failedResult|撤回失败的消息发送任务ID列表及对应的失败原因|object||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"successResult": [],
		"failedResult": {}
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/groupSendSampleText`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;content|内容||true|string||
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|加密消息id，根据此id可查询消息已读状态和撤回消息|string||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/groupSendSampleMarkdown`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;title|标题||true|string||
|&emsp;&emsp;text|内容||true|string||
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|加密消息id，根据此id可查询消息已读状态和撤回消息|string||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/groupSendSampleImageMsg`


**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`

**接口描述**:

**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;openConversationId|会话ID||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|加密消息id，根据此id可查询消息已读状态和撤回消息|string||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/groupSendSampleFile`


**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`


**接口描述**:

**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;openConversationId|会话ID||true|string||
|&emsp;&emsp;mediaId|媒体文件上传后获取的唯一标识||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|加密消息id，根据此id可查询消息已读状态和撤回消息|string||
|traceId|请求跟踪id|string||

**响应示例**:

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


## 根据手机号获取用户的userId


**接口地址**:`/api/open/getUserIdByMobile`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:

**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;userId|员工的userId|string||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"userId": "xxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/batchSendOtoSampleText`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;content|内容||true|string||
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||true|array|string|
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|消息id，根据此id，可用于查询消息是否已读和撤回消息|string||
|&emsp;&emsp;failPhones|失败的手机号列表和对应原因|object||
|&emsp;&emsp;invalidStaffIdList|无效的用户userId列表|array|string|
|&emsp;&emsp;flowControlledStaffIdList|被限流的userId列表|array|string|
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/batchSendOtoSampleMarkdown`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;title|标题||true|string||
|&emsp;&emsp;text|内容||true|string||
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||true|array|string|
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|消息id，根据此id，可用于查询消息是否已读和撤回消息|string||
|&emsp;&emsp;failPhones|失败的手机号列表和对应原因|object||
|&emsp;&emsp;invalidStaffIdList|无效的用户userId列表|array|string|
|&emsp;&emsp;flowControlledStaffIdList|被限流的userId列表|array|string|
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/batchSendOtoSampleImageMsg`


**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:

**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;mediaId|媒体文件上传后获取的唯一标识||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||false|array|string|
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|消息id，根据此id，可用于查询消息是否已读和撤回消息|string||
|&emsp;&emsp;failPhones|失败的手机号列表和对应原因|object||
|&emsp;&emsp;invalidStaffIdList|无效的用户userId列表|array|string|
|&emsp;&emsp;flowControlledStaffIdList|被限流的userId列表|array|string|
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/batchSendOtoSampleFile`


**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`


**接口描述**:

**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;mediaId|媒体文件上传后获取的唯一标识||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||false|array|string|
|&emsp;&emsp;userIds|接收机器人消息的用户的userId列表，每次最多传20个||false|array|string|
|&emsp;&emsp;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|
|&emsp;&emsp;processQueryKey|消息id，根据此id，可用于查询消息是否已读和撤回消息|string||
|&emsp;&emsp;failPhones|失败的手机号列表和对应原因|object||
|&emsp;&emsp;invalidStaffIdList|无效的用户userId列表|array|string|
|&emsp;&emsp;flowControlledStaffIdList|被限流的userId列表|array|string|
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/batchRecallOtoMessages`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


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


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|APP_ID|应用编码|header|true|||
|TIMESTAMP|时间戳|header|true|||
|TRACE_ID|序列号|header|true|||
|TOKEN|访问令牌|header|true|||
|batchRecallOtoMessagesDto|BatchRecallOtoMessagesDto|body|true|BatchRecallOtoMessagesDto|BatchRecallOtoMessagesDto|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;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|
|&emsp;&emsp;successResult|撤回成功的消息发送任务ID列表|array|string|
|&emsp;&emsp;failedResult|撤回失败的消息发送任务ID列表及对应的失败原因|object||
|traceId|请求跟踪id|string||


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"successResult": [],
		"failedResult": {}
	},
	"traceId": "20231231235959436337954"
}
```

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


**接口地址**:`/api/open/sftpGroupSendSampleImageMsg`


**请求方式**:`POST`

**请求数据类型**:`application/json`

**响应数据类型**:`application/json`

**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;openConversationId|会话ID||true|string||
|&emsp;&emsp;sftpId|sftp id||true|string||
|&emsp;&emsp;filePath|图片绝对路径||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|RGroupSendVo|


**响应参数**:


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


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/sftpGroupSendSampleFile`


**请求方式**:`POST`

**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;openConversationId|会话ID||true|string||
|&emsp;&emsp;sftpId|sftp id||true|string||
|&emsp;&emsp;filePath|文件绝对路径||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|RGroupSendVo|


**响应参数**:


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


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx"
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/sftpBatchSendOtoSampleImageMsg`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;sftpId|sftp id||true|string||
|&emsp;&emsp;filePath|图片绝对路径||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||false|array|string|
|&emsp;&emsp;userIds|接收机器人消息的用户的userId列表，每次最多传20个||false|array|string|


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|RBatchSendVo|


**响应参数**:


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


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```


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


**接口地址**:`/api/open/sftpBatchSendOtoSampleFile`


**请求方式**:`POST`


**请求数据类型**:`application/json`


**响应数据类型**:`application/json`


**接口描述**:


**请求示例**:


```javascript
{
  "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|
|&emsp;&emsp;robotCode|机器人的编码||true|string||
|&emsp;&emsp;sftpId|sftp id||true|string||
|&emsp;&emsp;filePath|文件绝对路径||true|string||
|&emsp;&emsp;phones|接收机器人消息的用户的手机号列表，每次最多传20个||false|array|string|
|&emsp;&emsp;userIds|接收机器人消息的用户的userId列表，每次最多传20个||false|array|string|


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|RBatchSendVo|


**响应参数**:


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


**响应示例**:
```javascript
{
	"success": true,
	"code": 0,
	"message": "成功",
	"data": {
		"processQueryKey": "jkasdfb8va9hndjksnxxxx",
		"failPhones": {},
		"invalidStaffIdList": [],
		"flowControlledStaffIdList": []
	},
	"traceId": "20231231235959436337954"
}
```