内部扩展 API — 机器人管理模块 (Bot)

基础信息

• 前缀URL: /v1/internal
• 主要功能: 账号转换为机器人、获取名下机器人列表、机器人设置、Bot Token 创建/列表/删除、Bot 指令 (Commands) 创建/获取/更新/删除。

---

接口列表

1. 账号申请/转为机器人

POST /v1/internal/bot.apply

将当前登录账号转换为由 owner_id 指定的主账号所掌控的 Bot 账号。

请求参数

参数名	类型	必填	描述
owner_id	number	是	拥有者用户 ID

请求示例

{
  "owner_id": 1
}

成功响应示例

{
  "success": true
}

---

2. 获取名下机器人列表

POST /v1/internal/bot.list

获取当前用户拥有的所有 Bot 账号列表。需 Header 携带 Token。

请求参数 无

成功响应示例

{
  "data": [
    {
      "id": 10,
      "username": "my_bot",
      "email": "bot@example.com",
      "avatar_url": "https://example.com/bot.png",
      "auto_accept_friends": true,
      "allow_topic_invites": true,
      "created_at": "2026-02-01 12:00:00"
    }
  ]
}

---

3. 机器人恢复为普通账号

POST /v1/internal/bot.revert

将指定 Bot 账号还原为普通用户账号。Owner 或 Bot 本人均可调用。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID

请求示例

{
  "bot_id": 10
}

成功响应示例

{
  "success": true
}

---

4. 更新机器人设置

POST /v1/internal/bot.settings.update

修改 Bot 的自动接受好友或允许频道邀请开关。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
auto_accept_friends	boolean	否	是否自动接受好友请求
allow_topic_invites	boolean	否	是否允许加入频道/话题邀请

请求示例

{
  "bot_id": 10,
  "auto_accept_friends": true,
  "allow_topic_invites": false
}

成功响应示例

{
  "success": true
}

---

5. 创建机器人 Token

POST /v1/internal/bot.token.create

为指定 Bot 生成一个新的访问 Token。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
name	string	否	Token 名称或备注

请求示例

{
  "bot_id": 10,
  "name": "Dev Server Token"
}

成功响应示例

{
  "token": "satori_bot_tok_1a2b3c4d5e..."
}

---

6. 获取机器人 Token 列表

POST /v1/internal/bot.token.list

查询 Bot 名下的已有 Token 列表。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID

请求示例

{
  "bot_id": 10
}

成功响应示例

{
  "data": [
    {
      "id": 1,
      "name": "Dev Server Token",
      "created_at": "2026-02-01 12:00:00"
    }
  ]
}

---

7. 删除机器人 Token

POST /v1/internal/bot.token.delete

删除/废除指定的机器人 Token。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
token_id	number	是	Token ID

请求示例

{
  "bot_id": 10,
  "token_id": 1
}

成功响应示例

{
  "success": true
}

---

8. 创建机器人指令

POST /v1/internal/bot.command.create

为 Bot 注册一个新的自定义命令/指令。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
name	string	是	指令名称（如 help 或 ping）
description	string	否	指令功能描述

请求示例

{
  "bot_id": 10,
  "name": "help",
  "description": "显示帮助菜单"
}

成功响应示例

{
  "command_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

---

9. 获取机器人指令列表

POST /v1/internal/bot.command.list

获取 Bot 注册的命令指令列表（如果是 Owner 调用会返回包括隐藏指令在内的全部指令）。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID

请求示例

{
  "bot_id": 10
}

成功响应示例

{
  "data": [
    {
      "id": 1,
      "command_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "name": "help",
      "description": "显示帮助菜单",
      "is_hidden": false,
      "created_at": "2026-02-01 12:00:00"
    }
  ]
}

---

10. 更新机器人指令

POST /v1/internal/bot.command.update

更新指定机器人指令的名称、描述或隐藏状态。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
command_id	string	是	指令 UUID
name	string	否	新指令名称
description	string	否	新指令描述
is_hidden	boolean	否	是否隐藏指令

请求示例

{
  "bot_id": 10,
  "command_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "description": "更新后的帮助指令描述",
  "is_hidden": false
}

成功响应示例

{
  "success": true
}

---

11. 删除机器人指令

POST /v1/internal/bot.command.delete

删除 Bot 的指定命令。

请求参数

参数名	类型	必填	描述
bot_id	number	是	机器人用户 ID
command_id	string	是	指令 UUID

请求示例

{
  "bot_id": 10,
  "command_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

成功响应示例

{
  "success": true
}