机器人开发者API
概述#
所有的接口采用graphql的方式提供，请求的uri：/api/bot/console，具体接口定义见下文详述，请求时在header里必须填充usertoken，且usertoken必须合法且未过期
对象定义#
bot#
机器人对象定义
| Field | Type | Description |
|---|---|---|
| bot_id | String | bot的id |
| owner_id | String | bot属主的user_id |
| bot_name | String | bot的名字 |
| bot_description | String | Optional. bot的描述信息 |
| bot_about | String | Optional. bot的描述信息，冗余字段，可以不用 |
| bot_avatar | String | Optional. bot的头像 |
| commands | BotCommand[] | Optional. bot支持的命令列表 |
| bot_permissions | u64 | Optional. bot的默认权限值，添加到服务器的时候，机器人默认拥有的权限。 |
| bot_class | u32 | Optional. bot的类别，具体描述见下文 |
| bot_token | String | Optional. 机器人的token，请求bot api时必须携带该token. |
| webhook | String | Optional. 支持webhook的uri，暂未使用. |
| market | Boolean | Optional. 是否上架到机器人市场. |
| guilds | String[] | Optional. 机器人是否支持内联查询（关于内联查询见API方法文档描述）， 该参数仅通过 getMe获取。 |
| enable_group_privacy_mode | Boolean | Optional. 是否开启了privacy模式，开启表示接收所有消息，否则仅接收用户加入和艾特机器人的消息 |
bot_class的定义如下：为4个字节共32个bit位，高位的第一个字节为第一层类别，第二个字节为第二层类别，第三个字节为第三层分类，第四个字节为第四层分类。
目前暂定:
- 工具辅助（0x1000000）
- 福利积分（0x2000000）
- 游戏娱乐（0x3000000）
- 影音媒体（0x4000000）
- 工作协同（0x5000000）
为了以后的扩展性，最好是取出高位的第一个字节当做分类，即：
- 工具辅助（0x1）
- 福利积分（0x2）
- 游戏娱乐（0x3）
- 影音媒体（0x4）
- 工作协同（0x5）
BotCommand#
描述一条bot命令的结构
| Field | Type | Description |
|---|---|---|
| command | String | 命令名字 |
| description | String | 命令描述信息 |
| visible_level | String | 可见级别：0值表示公开可见，即所有人都能看见该命令，1值表示私聊可见，即跟机器人私聊时才能看见该命令，2值表示服务器的管理人员才能看到该命令 |
| select_parameters | BotCommandParameter | Optional. BotCommandParameter类型的数组，表示该命令对应的选项参数 |
| form_parameters | BotCommandParameter | Optional. 表示该命令对应的表单参数 |
| hide | Boolean | Optional. 消息是否掩藏，比如机器人有个“签到”命令，用户签到时，会发送“@签到机器人 签到”，如果设置了hide为true，则只有发送者可见看到这个消息，而其他的人是看不到该消息的。 |
| clickable | BotCommand[] | Optional. 是否可点击，即比如发送了一个cancel命令后，是不是还可以点击聊天页面中的cancal文本继续给机器人发送cancal命令 |
| app_id | String | Optional. 标识此命令为小程序uri. 点击该命令时会跳转到小程序页面 |
| url | String | Optional. 标识此命令为web页面uri，点击该命令时会跳转到对应的web页面 |
[2022-10-19]针对小程序和H5两种命令时，当手动选择半屏或全屏选项，会自动将view(0:全屏，1:半屏)追加至跳转链接上，开发者只需填写原始链接即可。该选项由前端自动处理。
BotCommandParameter#
| Field | Type | Description |
|---|---|---|
| icon | String | 命令参数图标 |
| k | String | 命令参数的名字 |
| v | String | 命令参数的值，缺省，未用 |
graphql接口#
uri：比如开发环境的是：http://a1-dev.fanbook.mobi/api/bot/console
创建bot#
输入参数对象GraphqlNewBot的定义如下：
| Field | Type | Description |
|---|---|---|
| bot_name | String | 必选 |
| bot_avatar | Sting | 必选 |
| bot_description | String | 必选 |
| bot_permissions | String | 可选 |
| bot_class | i32 | 可选，类别，为0表示为分类 |
| market | Boolean | 可选，见上文的定义 |
| guilds | String[] | 可选，如果是填写为"[]" ,则会清楚guilds的内容，比如之前设置某部分服务器上架，现要上架到整个市场，则可以如此使用 |
| commands | BotCommand[] | 可选，见上文的定义 |
| enable_group_privacy_mode | Boolean | 可选，是否接收全量消息，默认是false |
示例：
请求：
mutation { new_bot(new_bot:{bot_name:"123",bot_avatar:"https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", bot_desc:"789", bot_permissions:1024,bot_class:1}){ bot_token bot_id bot_name bot_permissions }}
或者：
mutation ($newBot: GraphqlNewBot!){ new_bot(new_bot:$newBot){ bot_token bot_id bot_name bot_permissions }}
参数：
{ "newBot":{ "bot_name":"123", "bot_avatar":"https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "bot_description":"789", "bot_permissions":1024, "bot_class":1 }}返回：
{ "data": { "new_bot": { "bot_token": "a9e0d33c44d6eda7e39a24960d33a4dbecb3997e1800aadf99bbbd0936341db15e10b7690b8b0e619bf281562820c10f", "bot_id": "312142813057777664", "bot_name": "123", "bot_permissions": 1024 } }}
获取单个bot的接口#
请求：
query ($bot_id: String!) { bot(bot_id:$bot_id){ bot_id owner_id bot_name commands{ command description form_parameters{ icon k v } } bot_class bot_permissions }}
参数：
{ "bot_id":"258501794529804288"}
返回：
{ "data": { "bot": { "bot_id": "258501794529804288", "owner_id": "86655584392323072", "bot_name": "机器好人", "commands": [ { "command": "绑定哔哩账号", "description": "绑定哔哩账号", "form_parameters": [ [ { "icon": null, "k": "哔哩哔哩ID", "v": null } ] ] }, ], "bot_class": null, "bot_permissions": null } }}
获取属主的所有机器人的接口#
请求：
query ($owner_id: String!) { bots(owner_id:$owner_id){ bot_id owner_id bot_name bot_avatar commands{ command description form_parameters{ icon k v } } bot_class bot_permissions bot_token }}
参数：
{ "owner_id":"86655584392323072"}返回：
{ "data": { "bots": [ { "bot_id": "258060750621245440", "owner_id": "86655584392323072", "bot_name": "任务机器人", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": [ { "command": "任务列表", "description": "我已经添加的任务", "form_parameters": null } ], "bot_class": null, "bot_permissions": null, "bot_token": "e79f1400757bee0729b49fc54e3d87e4e3b90def49219231aa8a7df12212142b" }, { "bot_id": "309982120225275904", "owner_id": "86655584392323072", "bot_name": "123", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": null, "bot_class": 1, "bot_permissions": 1024, "bot_token": "233b966b8ac48317011e50b5817b5602944d6501ea1818e303e2e41d52323c64" }, { "bot_id": 309881574235570176, "owner_id": 86655584392323072, "bot_name": "测试", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": null, "bot_class": null, "bot_permissions": null, "bot_token": "6a84719ab2438b4dd3e9285fc6f386bd761966c98530e9cdc97f67c5794bec57" }, { "bot_id": "309982298428669952", "owner_id": "86655584392323072", "bot_name": "123", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": null, "bot_class": 1, "bot_permissions": 1024, "bot_token": "838cf61b201d8efbbb1db2a871bd58bb868667fcadcb21fc58616c79fd3743e3" }, { "bot_id": "309985355212259328", "owner_id": "86655584392323072", "bot_name": "123", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": null, "bot_class": 1, "bot_permissions": 1024, "bot_token": "5bb8b8eb9b1528145f1d6fb0da2fd2bfdd320a7bff88f87cf98fc675d1afe04c" }, { "bot_id": "309983624910864384", "owner_id": "86655584392323072", "bot_name": "123", "bot_avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg", "commands": null, "bot_class": 1, "bot_permissions": 1024, "bot_token": "000f4a10d1f92896fb1306a8ca66881c4c5e4520335f624ec77cc176f865f40d" } ] }}重置机器人token#
请求：
mutation ($bot_id:String!){ reset_token(reset_token:{bot_id:$bot_id})}参数：
{ "bot_id":"309985355212259328"}返回：
{ "data": { "reset_token": "5bb8b8eb9b1528145f1d6fb0da2fd2bf2835fd585e16a815b6b968770f4cf49f9b006ea713db2d0bdf8430045b566798" }}删除bot的接口#
请求：
mutation ($bot_id:String!){ delete_bot(bot_id:$bot_id)}参数：
{ "bot_id":"309881574235570176"}返回：
{ "data": { "delete_bot": true }}更新机器人接口#
请求方式一：
mutation ($bot_id:String!){ update_bot(update_bot:{bot_id:$bot_id,bot_name:"test"})}update_bot输入对象还有以下字段：bot_name, bot_avatar, bot_desc, bot_permissions, bot_class, market、commands、guilds和enable_group_privacy_mode，字段的解释见bot对象定义。
参数：
{ "bot_id":"309985355212259328"}返回：
{ "data": { "update_bot": true }}请求方式二：
mutation ($updateBot:GraphqlUpdateBot!){ update_bot(update_bot:$updateBot)}参数：
{ "updateBot": { "bot_name": "123456", "bot_id": "242162881485864960", "bot_avatar":"123456", "bot_description": "56789", "market":true, "guilds":["123"] }}返回：
{ "data": { "update_bot": true }}错误处理#
比如以下错误结果：
{ "data": null, "errors": [ { "message": "Record Not Found", "locations": [ { "line": 2, "column": 5 } ], "path": [ "delete_bot" ] } ]}返回的data会为null，且errors记录了详细信息。