Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 146 additions & 1 deletion src/api/bot/v1/bot.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,35 @@ title: bot
---

未特别说明情况下请求域名均为 `https://chat-go.jwzhd.com`
没写请求/响应项目表示不需要相关参数.
没写请求/响应项目表示不需要相关参数.
`GET` 接口的参数均放在 URL 查询字符串中,无需请求正文。

## 获取机器人信息

仅返回当前 token 对应的机器人,无需传入 botId。停用或封禁状态不影响此只读查询;响应不包含 token、机器人配置或创建者信息。

```http
GET /open-apis/v1/bot/info?token={机器人token}
```

响应体:

```JSONC
{
"code": 1, // 请求状态码,1为正常
"msg": "success", // 返回消息
"data": {
"botId": "987654", // 机器人ID
"nickname": "示例机器人", // 机器人名称
"avatarUrl": "https://example.com/bot.png", // 头像URL
"introduction": "示例机器人简介", // 简介
"isStop": 0, // 停用状态,0-正常,1-停用
"isBanned": false, // 当前是否处于封禁状态
"banEndTime": 0, // 封禁结束的Unix秒时间戳,永久封禁为0,未封禁或已到期也为0,需结合isBanned判断
"banReason": "" // 当前封禁原因,未封禁或已到期为空字符串
}
}
```

## 机器人发送信息

Expand Down Expand Up @@ -345,3 +373,120 @@ POST /open-apis/v1/bot/messages?token={机器人token}&chat-id={目标信息ID}&
"msg": "success" // 返回消息
}
```

## 机器人所在群列表

仅包含当前机器人仍在其中、且未解散的群,已退出或被移除的群不返回。按群内部 ID 倒序排列,`total` 为全部符合条件的群数量;无结果或页码超出结果范围时 `list` 为空数组。当前不支持按群名称搜索。停用或封禁状态不影响此只读查询;列表可能包含封禁中的群,可通过群信息查询其状态。

```http
GET /open-apis/v1/bot/groups?token={机器人token}&page={页码,默认1,范围1–1000000}&size={每页条数,默认20,范围1–100}
```

响应体:

```JSONC
{
"code": 1, // 请求状态码,1为正常
"msg": "success", // 返回消息
"data": {
"list": [
{
"groupId": "123456", // 群ID,可用于群信息及消息接口
"name": "示例群", // 群名称
"avatarUrl": "https://example.com/group.png" // 群头像URL
}
// ...
],
"total": 1, // 符合条件的群总数
"page": 1, // 当前页码
"size": 20 // 每页条数
}
}
```

## 获取群信息

机器人必须仍在目标群中,且群未解散;查询本身不要求机器人具有群管理权限。`permissions` 表示当前机器人在该群获得的权限,0 为未授权,1 为已授权,实际写操作仍会执行各自的权限及业务校验。停用或封禁状态不影响此只读查询。

```http
GET /open-apis/v1/group/info?token={机器人token}&groupId={群ID}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/v1/group 路由不要放到 /v1/bot 下面

```

响应体:

```JSONC
{
"code": 1, // 请求状态码,1为正常
"msg": "success", // 返回消息
"data": {
"groupId": "123456", // 群ID
"name": "示例群", // 群名称
"avatarUrl": "https://example.com/group.png", // 群头像URL
"introduction": "示例群简介", // 群简介
"headcount": 20, // 群人数
"msgTypeLimit": "1,2", // 逗号分隔的消息类型数字ID,如1,2;空字符串表示无限制。与设置接口的英文类型参数格式不同
"isBanned": false, // 当前是否处于封禁状态
"banEndTime": 0, // 封禁结束的Unix秒时间戳,永久封禁为0,未封禁或已到期也为0,需结合isBanned判断
"banReason": "", // 当前封禁原因,未封禁或已到期为空字符串
"permissions": { // 当前机器人在该群的管理权限
"allowEditGroupInfo": 1, // 是否允许修改群信息,0/1
"allowGagMember": 1, // 是否允许禁言成员,0/1
"allowRemoveMember": 0, // 是否允许移除成员,0/1
"allowGroupTagManage": 1, // 是否允许管理群标签,0/1
"allowGetGroupMembers": 0 // 是否允许获取群成员列表,0/1,默认0
}
}
}
```

## 获取群成员列表

群主或管理员须在群内机器人权限设置中开启“允许获取群成员列表”,默认关闭;仅有禁言、踢人等其他权限不能读取成员列表。开启授权后,机器人可以读取完整成员名单,包括开启“隐藏群成员”的群;关闭授权后后续请求会被拒绝,机器人退出后重新加入需要重新授权。机器人必须仍在目标群中且群未解散。仅返回仍在群中的未删除用户,按成员等级及群成员记录 ID 倒序,`list` 与 `total` 使用相同的成员过滤条件。接口沿用现有开放接口限流,触发时返回 1007。不返回手机号、邮箱、密码或其他个人资料。

```http
GET /open-apis/v1/group/members?token={机器人token}&groupId={群ID}&page={页码,默认1,范围1–1000000}&size={每页数量,默认20,范围1–100}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

```

响应体:

```JSONC
{
"code": 1, // 请求状态码,1为正常
"msg": "success", // 返回消息
"data": {
"list": [
{
"userId": "654321", // 用户ID
"nickname": "示例用户", // 账号昵称
"groupNickname": "群内昵称", // 群昵称,未设置时为空字符串,展示时可优先使用群昵称
"avatarUrl": "https://example.com/avatar.png", // 头像URL
"userLevel": "member" // 群成员角色,owner-群主,admin-管理员,member-普通成员
}
// ...
],
"total": 1, // 符合条件的成员总数
"page": 1, // 当前页码
"size": 20 // 每页数量
}
}
```

MCP 对应只读工具 `list_group_members`,权限限制与 REST 接口一致。

```json
{"name":"list_group_members","arguments":{"groupId":"123456","page":1,"size":20}}
```

凭证使用 MCP 的 Authorization: Bearer 请求头,不放在工具参数中。

## 通用错误码

业务结果请检查响应中的 `code`,这些业务错误仍返回 HTTP 200。

| 错误码 | 说明 |
| ---- | ---- |
| 1 | 成功 |
| 1002 | token 缺失或请求参数有误,含 groupId 缺失、分页参数越界等情况 |
| 1003 | token 无效或对应机器人已删除;查询群相关接口时也表示机器人未加入该群、群不存在、群已解散或未获得成员列表权限 |
| 1007 | 请求过于频繁,请降低频次 |
| -1 | 数据库查询失败,请稍后重试 |