Developer Center
开放接口文档
基础域名：https://work.yueqiancloud.com（生产）
接口默认 Content-Type 为
application/json。请求体中的 robotId 为必填。
接口总览
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /send | 下发指令到机器人（核心入口） |
| POST | 开发者 callbackUrl | 异步推送执行结果、新消息、群二维码和查询数据 |
| POST | /robot/verify | 校验机器人 ID 是否有效 |
| GET/POST | /runtime/config | 获取当前运行环境配置（Host/端口） |
1) 下发指令：POST /send
请求体通用字段
robotId：机器人 ID（必填）list：指令数组（必填）encryptType：0 明文，1 AES（可选）messageId：自定义消息 ID（可选）meta：透传信息（可选）callbackUrl：本次指令的异步回调地址（可选）callbackSecret：HMAC-SHA256 回调签名密钥（可选，建议配置）
常用 type
| type | 含义 | 用途 |
|---|---|---|
| 201 | 停止并回到首页 | 重置执行状态 |
| 202 | 循环接收新消息 | 常驻监听新消息 |
| 203 | 发送消息 | 向目标群/人发送文本等 |
| 204 | 回复消息 | 对指定消息做回复 |
| 227 | 逐条转发 | 消息逐条分发 |
| 228 | 合并转发 | 消息合并后分发 |
示例：开启循环接收新消息（202）
curl -X POST "https://work.yueqiancloud.com/send" \
-H "Content-Type: application/json" \
-d '{
"robotId":"YOUR_ROBOT_ID",
"list":[{"type":202}]
}'示例：停止并回到首页（201）
curl -X POST "https://work.yueqiancloud.com/send" \
-H "Content-Type: application/json" \
-d '{
"robotId":"YOUR_ROBOT_ID",
"list":[{"type":201}]
}'Developer Callback
2) 开发者异步回调
调用 /send 后无需持续轮询。越前服务会把指令结果、企微新消息、群二维码和查询数据异步 POST 到你的服务器。
回调地址优先级
- 单次覆盖：
/send请求中传入callbackUrl和callbackSecret。 - 机器人默认：在 App「高级设置 → 消息回调地址」中保存长期回调地址。
{
"robotId": "YOUR_ROBOT_ID",
"messageId": "create-group-001",
"meta": "{\"businessId\":\"ORDER-001\"}",
"callbackUrl": "https://your-domain.com/callback",
"callbackSecret": "YOUR_CALLBACK_SECRET",
"list": [{"type": 206, "groupName": "客户服务群", "selectList": []}]
}回调事件
| eventType | 触发场景 | 典型数据 |
|---|---|---|
command_result | 指令执行完成 | 执行状态、错误码 |
incoming_message | 收到企微新消息 | 发送人、群名、文本/媒体内容 |
group_qrcode | 创建或修改群后获取二维码 | 群名称、二维码链接 |
robot_data | 查询群、好友、企业等数据 | 查询类型和结构化结果 |
公共回调结构
{
"eventId": "uuid",
"eventType": "command_result",
"timestamp": 1753286400,
"robotId": "YOUR_ROBOT_ID",
"messageId": "create-group-001",
"meta": "{\"businessId\":\"ORDER-001\"}",
"data": {}
}HMAC-SHA256 验签
X-Worktool-Timestamp：Unix 秒级时间戳X-Worktool-Signature：十六进制小写签名- 签名原文：
timestamp + "." + rawBody - 建议校验时间窗口不超过 ±300 秒
回调超时为 10 秒；非 2xx 或网络错误会按 1s、3s、10s 最多重试 3 次。
3) 校验机器人 ID：POST /robot/verify
curl -X POST "https://work.yueqiancloud.com/robot/verify" \
-H "Content-Type: application/json" \
-d '{"robotId":"YOUR_ROBOT_ID"}'