云湖机器人开发文档

Hehe Nya! 发布于 2025-02-02 20:25:34

开发须知

基础概念

在开发之前，建议优先浏览开发须知，了解平台的使用逻辑

机器人

机器人可以理解为一个虚拟用户，可以被多个用户添加为好友。不同用户和机器人的对话是相互隔离。
每个机器人拥有两个主要功能：

  1. 订阅事件功能。任何人发送到机器人的消息都可以推送到订阅URL链接，用于机器人创建者根据用户发送到机器人的消息进行回复。
  2. 通过机器人发送消息给用户。给机器人的好友用户发送或者回复消息

群

群即常见的群聊功能，每个群也拥有机器人的两个功能，和机器人不同的是，不同用户发送到群的消息任何人都能看到。

接口参数含义说明

userId: 用户ID

recvId: 接收消息的用户ID、群ID

recvType: 接收类型，取值user、group

接口调用方式

平台中所有接口都是通过HTTP/HTTPS协议进行数据交互

HTTP Method： POST、 GET

授权：所有接口不需要身份验证及登录等操作，部分接口带有token信息，便于接入，如token信息泄露可以联系官方人员进行修改。

频次限制：注意每个接口有不同的频次控制

机器人开发流程

  1. 在软件中创建机器人
  2. 开发订阅消息接收Web程序，将URL填入官网控制台中（系统会自动推送机器人消息到该URL）
  3. 从官网控制台中查看机器人发送消息URL
  4. 在订阅消息的Web程序中收到系统推送的消息后，根据消息内容或指令进行消息回复

服务端API列表

API名称 介绍 速率限制 状态
发送消息 1、给机器人用户发送消息<br />2、给群发送消息 10次/秒 可用
批量发送消息 给机器人多位用户发送消息 10次/秒 可用
编辑消息 对发出的消息进行修改 10次/秒 可用
设置看板内容 对机器人看板内容进行设置修改 10次/秒 可用
撤回消息 支持撤回群内消息、机器人消息 10次/秒 可用
获取消息列表 获取最新消息列表，获取指定消息前后消息 10次/秒 可用
获取机器人用户列表 待上线

错误代码

错误码 错误信息 说明
1 success 正常
1002 invalid parameter 参数缺失或者有误
1003 unauthorized 未授权
1004 bot banned 机器人被封禁
1005 chat banned 会话被封禁
1007 frequency limit 触发频次限制

消息列表

请求URL

https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxxxxxxx

请求类型

GET

请求示例

curl --location 'https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxx&chat-id=xxxx&chat-type=group&message-id=dad25257f71f41098f733a5079183080&before=2'

请求头

Content-Type: "application/json; charset=utf-8"

请求参数

字段 类型 是否必填 说明
chat-id string 是 获取消息对象ID<br /> 用户: 使用userId<br />群: 使用groupId
chat-type string 是 获取消息对象类型<br /> 用户: user<br />群: group
message-id string 否 消息ID，不填时可以配合before参数返回最近的N条消息
before int 否 指定消息ID前N条，默认0条
after int 否 指定消息ID后N条，默认0条

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

请求示例

// 获取群ID【xxx】中最新 10 条消息，共返回 10 条消息
https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxx&chat-id=xxx&chat-type=group&before=10

// 获取群ID【xxx】中消息 ID【xxxx】前 10 条消息，共返回 11 条消息
https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxx&chat-id=xxx&chat-type=group&message-id=xxxx&before=10

// 获取群ID【xxx】中消息 ID【xxxx】后 10 条消息，共返回 11 条消息
https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxx&chat-id=xxx&chat-type=group&message-id=xxxx&after=10

// 获取群ID【xxx】中消息 ID【xxxx】前后各 10 条消息，共返回 21 条消息
https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxx&chat-id=xxx&chat-type=group&message-id=xxxx&before=10&after=10

// 获取用户ID【xxx】中消息 ID【xxxx】前 10 条消息，共返回 11 条消息
https://chat-go.jwzhd.com/open-apis/v1/bot/messages?token=xxxxx&chat-id=xxx&chat-type=user&message-id=xxxx&before=10

响应示例

{
    "code": 1,
    "data": {
        "list": [
            {
                "msgId": "dad25257f71f41098f733a5079183080",
                "parentId": "",
                "senderId": "7999713",
                "senderType": "user",
                "senderNickname": "NH₃·H₂O",
                "contentType": "markdown",
                "content": {
                    "text": "#不要潜水快来嗨皮啊"
                },
                "sendTime": 1709102439694,
                "commandName": "",
                "commandId": 0
            },
            {
                "msgId": "672d5171b9474c7e870ac311361ac85b",
                "parentId": "",
                "senderId": "8380181",
                "senderType": "user",
                "senderNickname": "梵高",
                "contentType": "text",
                "content": {
                    "text": "是在潜水"
                },
                "sendTime": 1708751609482,
                "commandName": "",
                "commandId": 0
            }
        ],
        "total": 2
    },
    "msg": "success"
}

图片上传

请求URL

https://chat-go.jwzhd.com/open-apis/v1/image/upload?token=xxxxxxxxxx

请求类型

POST

请求示例

curl --location 'https://chat-go.jwzhd.com/open-apis/v1/image/upload?token=xxxxxxxxxx' \
--form 'image=@"D:\\image\\aaa\\bbb.png"'

请求头

Content-Type: "multipart/form-data;"

请求参数

字段 类型 是否必填 说明
image file 是 图片内容，仅限单个图片，上传图片大小不超过 10MB

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

完整示例

图片上传响应示例

{
    "code": 1,
    "data": {
        "imageKey": "xxxxxxxxxxxx"
    },
    "msg": "success"
}

Python 代码示例

import requests

url = "https://chat-go.jwzhd.com/open-apis/v1/image/upload?token=xxxxxx"

files=[
  ('image',open('6bca4389875743205502a57bb90fcad0.gif','rb'))
]

response = requests.request("POST", url, files=files)
print(response.text)

机器人发送消息

请求URL

https://chat-go.jwzhd.com/open-apis/v1/bot/send?token=xxxxxxxxxx

请求类型

POST

请求示例

curl --location --request POST 'https://chat-go.jwzhd.com/open-apis/v1/bot/send?token=xxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recvId": "7058262",
    "recvType": "user",
    "contentType": "text",
    "content": {
        "text": "这里是消息内容"
    }
}'

请求头

Content-Type: "application/json; charset=utf-8"

请求参数

字段 类型 是否必填 说明
recvId string 是 接收消息对象ID<br /> 用户: userId<br />群: groupId
recvType string 是 接收对象类型<br /> 用户: user<br />群: group
contentType string 是 消息类型，取值如下<br />text\image\file\markdown\html （html支持标签）
content Content对象 是 消息对象
parentId string 否 引用消息 ID
Content对象

contentType为text

字段 类型 是否必填 说明
text string 是 消息正文
buttons Button对象列表 否 消息中包括button

contentType为image

字段 类型 是否必填 说明
imageKey string 是 图片Key, 通过图片上传接口获得
buttons Button对象列表 否 消息中包括button

contentType为markdown

字段 类型 是否必填 说明
text string 是 markdown字符串
buttons Button对象列表 否 消息中包括button

contentType为file

字段 类型 是否必填 说明
fileName string 是 文件名
fileUrl string 是 文件URL
buttons Button对象列表 否 消息中包括button
Button对象
字段 类型 是否必填 说明
text string 是 按钮上的文字
actionType int 是 1: 跳转URL<br />2: 复制<br />3: 点击汇报
url string 否 当actionType为1时使用
value string 否 当actionType为2时，该值会复制到剪贴板<br />当actionType为3时，该值会发送给订阅端

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

完整示例

发送文本消息请求示例

{
    "recvId": "7058262",
    "recvType": "user",
    "contentType": "text",
    "content": {
        "text": "这里是消息内容",
        "buttons": [
            [
                {
                    "text": "复制",
                    "actionType": 2,
                    "value": "xxxx"
                },
                {
                    "text": "点击跳转",
                    "actionType": 1,
                    "url": "http://www.baidu.com"
                }
            ]
        ]
    }
}

机器人批量发送消息

请求URL

https://chat-go.jwzhd.com/open-apis/v1/bot/batch_send?token=xxxxxxxxxx

请求示例

curl --location --request POST 'https://chat-go.jwzhd.com/open-apis/v1/bot/batch_send?token=xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recvIds": ["7058262", "7058263"],
    "recvType": "user",
    "contentType": "text",
    "content": {
        "text": "这里是消息内容"
    }
}'

请求头

Content-Type: "application/json; charset=utf-8"

请求参数

字段 类型 是否必填 说明
recvIds list 是 接收消息对象ID<br /> 用户: userIds<br />群: groupIds
recvType string 是 接收对象类型<br /> 用户: user<br />群: group
contentType string 是 消息类型，取值如下<br />text\image\file\markdown\html
content Content对象 是 消息对象
Content对象

contentType为text

字段 类型 是否必填 说明
text string 是 消息正文
buttons Button对象列表 否 消息中包括button

contentType为image

字段 类型 是否必填 说明
imageKey string 是 图片Key, 通过图片上传接口获得
buttons Button对象列表 否 消息中包括button

contentType为markdown

字段 类型 是否必填 说明
text string 是 markdown字符串
buttons Button对象列表 否 消息中包括button

contentType为file

字段 类型 是否必填 说明
fileName string 是 文件名
fileUrl string 是 文件URL
buttons Button对象列表 否 消息中包括button
Button对象
字段 类型 是否必填 说明
text string 是 按钮上的文字
actionType int 是 1: 跳转URL<br />2: 复制<br />3: 点击汇报
url string 否 当actionType为1时使用
value string 否 当actionType为2时，该值会复制到剪贴板<br />当actionType为3时，该值会发送给订阅端

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

完整示例

批量发送文本消息请求示例

{
    "recvIds": ["7058262", "7058263"],
    "recvType": "user",
    "contentType": "text",
    "content": {
        "text": "这里是消息内容",
        "buttons": [
            [
                {
                    "text": "复制",
                    "actionType": 2,
                    "value": "xxxx"
                },
                {
                    "text": "点击跳转",
                    "actionType": 1,
                    "url": "http://www.baidu.com"
                }
            ]
        ]
    }
}

机器人编辑（修改）自己发送的消息

请求URL

https://chat-go.jwzhd.com/open-apis/v1/bot/edit?token=xxxxxxxxxx

请求示例

curl --location --request POST 'https://chat-go.jwzhd.com/open-apis/v1/bot/edit?token=xxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msgId": "xxxxxxx",
    "recvId": "7058262",
    "recvType": "user",
    "contentType": "text",
    "content": {
        "text": "这里是消息内容"
    }
}'

请求头

Content-Type: "application/json; charset=utf-8"

请求参数

字段 类型 是否必填 说明
msgId string 是 消息ID
recvId string 是 接收消息对象ID，用户: userId 群: groupId <br /> 需与原消息保持一致
recvType string 是 接收对象类型，用户: user 群: group <br /> 需与原消息保持一致
contentType string 是 消息类型，取值如下<br />text\image\file\markdown\html
content Content对象 是 消息对象, 具体值见发送消息

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

撤回消息

请求URL

https://chat-go.jwzhd.com/open-apis/v1/bot/recall?token=xxxxxxxxxx

请求示例

curl --location --request POST 'https://chat-go.jwzhd.com/open-apis/v1/bot/recall?token=xxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msgId": "xxxxxxx",
    "chatId": "7058262",
    "chatType": "user"
}'

请求头

Content-Type: "application/json; charset=utf-8"

请求参数

字段 类型 是否必填 说明
msgId string 是 消息ID
chatId string 是 消息对象ID，用户: userId 群: groupId
chatType string 是 消息对象类型，用户: user 群: group

响应内容

字段 类型 说明
code int 响应代码
msg string 响应信息，包括异常信息
data Object 返回数据

事件订阅详述

事件订阅是系统可以将软件中的消息或其他事件（加入、退出群事件和关注、取关机器人事件）推送到你的服务器中，你的服务器可以根据对应的消息或者事件做出相应的反应。<br />推送是通过HTTP协议以POST请求的方式推送JSON格式的数据

使用场景

  • 你希望能对用户输入的内容做出相应反应时，比如当用户输入1+1=,你可以在服务器端收到这条消息，然后计算出结果，再通过消息发送接口告诉用户计算结果

事件列表

事件名称 介绍 取值 状态
普通消息事件 普通消息 message.receive.normal 可用
指令消息事件 指令消息 message.receive.instruction 可用
关注机器人事件 关注机器人事件 bot.followed 可用
取消关注机器人事件 取消关注机器人事件 bot.unfollowed 可用
加入群事件 用户加入群事件 group.join 可用
退出群事件 用户退出群事件 group.leave 可用
按钮事件 消息中按钮点击事件 button.report.inline 可用

消息事件

数据内容

字段 类型 说明
version string 事件内容版本号
header Header对象 包括事件的基础信息
event Event对象 包括事件的内容。注意：Event对象的结构会在不同的eventType下发生变化

Header对象

字段 类型 说明
eventId string 事件ID，全局唯一
eventTime int 事件产生的时间，毫秒13位时间戳
eventType string 事件类型

Event对象

字段 类型 说明
sender Sender对象 发送者的信息
message Message对象 消息内容

Sender对象

字段 类型 说明
senderId string 发送者ID，给用户回复消息需要该字段
senderType string 发送者用户类型，取值：user
senderUserLevel string 发送者级别，取值：owner、administrator、member、unknown
senderNickname string 发送者昵称

Chat对象

字段 类型 说明
chatId string 聊天对象ID
chatType string 聊天对象类型，取值: bot、group

Message对象

字段 类型 说明
msgId string 消息ID，全局唯一
parentId string 引用消息时的父消息ID
sendTime int 消息发送时间，毫秒13位时间戳
chatId string 当前聊天的对象ID<br />单聊消息，chatId即对方用户ID<br />群聊消息，chatId即群ID<br />机器人消息，chatId即机器人ID
chatType string 当前聊天的对象类型<br />group 群聊<br />bot 机器人
contentType string 当前消息类型<br />text 文本消息<br />image 图片消息<br />markdown Markdown消息<br />file 文件消息
content Content对象 消息正文
commandId int 指令ID，可用来区分用户发送的指令
commandName string 指令名称，可用来区分用户发送的指令

普通消息、指令消息事件JSON结构体示例

{
    "version":"1.0",
    "header":{
        "eventId":"xxxxx",
        "eventTime":1647735644000,
        "eventType":"xxxxxx"
    },
    "event":{
        "sender":{
            "senderId":"xxxxx",
            "senderType":"user",
            "senderUserLevel":"member",
            "senderNickname":"昵称",
        },
        "chat":{
            "chatId":"xxxxx",
            "chatType":"group"
        },
        "message":{
            "msgId":"xxxxxx",
            "parentId":"xxxx",
            "sendTime":1647735644000,
            "chatId":"xxxxxxxx",
            "chatType":"group",
            "contentType":"text",
            "content":{
                "text":"早上好"
            },
            "commandId":98,
            "commandName":"计算器"
        }
    }
}

按钮汇报事件JSON结构体示例

{
    "msgId": "xxxxxx",
    "recvId": "xxx",
    "recvType": "bot",
    "time": 1702050343000,
    "userId": "xxx",
    "value": "value"
}
0
0
5
分享
0 回复
暂无评论
关注：687
文章：9409
云湖
加作者好友
Hehe Nya!
推荐群聊
云湖美化交流群
迅银
广告群
云湖树洞
傻逼的一家
关注：687
文章：9409
云湖
加作者好友
Hehe Nya!
推荐群聊
云湖美化交流群
迅银
广告群
云湖树洞
傻逼的一家
京ICP备20012521号-7 增值电信业务经营许可证：京B2-20210468
Copyright © 2025 北京九万智达科技有限公司