From 680905533913cf64545976243cb47fd5f35c5e75 Mon Sep 17 00:00:00 2001 From: LogicTneXus <385158091@qq.com> Date: Sat, 7 Nov 2026 21:30:34 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E4=BA=86=E2=80=9C=E8=8E=B7?= =?UTF-8?q?=E5=8F=96=E6=9C=BA=E5=99=A8=E4=BA=BA=E4=BF=A1=E6=81=AF=E2=80=9D?= =?UTF-8?q?=E5=92=8C=E2=80=9C=E8=8E=B7=E5=8F=96=E6=9C=BA=E5=99=A8=E4=BA=BA?= =?UTF-8?q?=E6=89=80=E5=9C=A8=E7=BE=A4=E5=88=97=E8=A1=A8=E2=80=9D=E5=92=8C?= =?UTF-8?q?=E2=80=9C=E6=9C=BA=E5=99=A8=E4=BA=BA=E6=89=80=E5=9C=A8=E7=BE=A4?= =?UTF-8?q?=E6=88=90=E5=91=98=E5=88=97=E8=A1=A8=E2=80=9D=E5=92=8C=E2=80=9C?= =?UTF-8?q?=E8=8E=B7=E5=8F=96=E7=BE=A4=E4=BF=A1=E6=81=AF=E2=80=9D=E7=9A=84?= =?UTF-8?q?=E5=9B=9B=E4=B8=AAapi?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/api/bot/v1/bot.md | 147 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 1 deletion(-) diff --git a/src/api/bot/v1/bot.md b/src/api/bot/v1/bot.md index 25b4ab5b9..6c8ced92c 100644 --- a/src/api/bot/v1/bot.md +++ b/src/api/bot/v1/bot.md @@ -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": "" // 当前封禁原因,未封禁或已到期为空字符串 + } +} +``` ## 机器人发送信息 @@ -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} +``` + +响应体: + +```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} +``` + +响应体: + +```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 | 数据库查询失败,请稍后重试 |