跳到主要内容

API可用方法

URL格式#

URL: https://a1.fanbook.cn/{URI}

URI: /api/bot/{bot token}/{api}

Bot Token: 创建机器人时生成的bot token，可以在机器人管理页面上得到

可用方法#

所有的请求方法是大小写敏感的

如非特别说明，请用 POST 方法. 消息体支持 application/json 、 application/x-www-form-urlencoded 和 multipart/form-data 编码，将以 application/json 为主

调用成功后, 返回的消息内容是 application/json 编码的

注意，对于 GET 请求，按restFul规范把参数写在uri

错误码#

对于业务可能返回的错误概述，请参考 API错误码

API接口

机器人#

Bot信息#

使用场景#

返回bot的基本信息， 返回的是一个User 对象，并包含一个可以用来ws连接的user token

Uri#

Get: /api/bot/{bot token}/getMe

请求载体#

无

响应载体#

{    "ok": true,    "result": {        "id": 31505*****380608,        "is_bot": true,        "first_name": "bot-25569*****",        "last_name": "2556974225*****",     // owner的id        "username": "bot-2556974225822*****",        "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d****e2b2fe42fb5.jpg",        "user_token": "a169e07d91846a31602db66a30c6b1ab32d6ab5ab39c1f5ffbed8aa*********",        "owner_id": 2556974225*****,        "can_join_groups": false,        "can_read_all_group_messages": false,        "supports_inline_queries": false    }}

获取命令列表#

使用场景#

使用该方法获取当前机器人的所有命令，成功则返回 BotCommand 的数组

Uri#

Get: /api/bot/{token}/getMyCommands

请求载体#

无

响应载体#

设置服务器昵称#

使用场景#

设置机器人的服务器昵称

Uri#

Post: /api/bot/{bot token}/robot/setGuildNick

请求载体#

ParameterTypeRequiredDescription
guild_IdString是服务器ID
bot_idString是机器人
nicknameString是服务器昵称

响应载体#

消息#

获取消息(长轮询)#

使用场景#

获取批量信息 Message

Uri#

Post: /api/bot/{bot token}/getUpdates

请求载体#

ParameterTypeRequiredDescription
offsetInteger可选所有的Update保存在一个队列里，offset表示从队列尾部取多少条目的Update对象，调用后，在该offset之前的Update对象都会被删除掉。该队列的最大长度是10000，超过100000条时，较旧的Update对象会被删除
limitInteger可选表示调用getUpdate返回的Update最大条目数，取值范围1~100，默认取值100（当取值0时会设为10）
timeoutInteger可选长轮询调用时，等待的时长，以秒为单位，默认是60
msg_typeString可选circle 代表获取圈子相关消息，需开启全量开关，需加白

说明#

使用这个接口接收服务器里所有的Update，这是一个长轮询的设计方案，简单说就是有消息立刻返回，无消息会hold住等待新消息，为性能考虑不接受多实例并发调用。返回一组Update对象，默认情况下只能收到公开频道的NewJoin消息和艾特机器人的消息，如果想接收所有类型的消息，需要去机器人编辑页面打开全量开关，此时才能接收所有类型的消息，比如圈子，表态，pin，图片，视频等等消息。目前需加白名单。 也支持get请求，参数需以query string的形式加在链接里。

获取消息(简易版)#

使用场景#

获取批量信息 Message

Uri#

Post: /api/bot/{bot token}/v2/getUpdates

请求载体#

ParameterTypeRequiredDescription
msg_typeString可选circle 代表获取圈子相关消息，需开启全量开关，需加白

说明#

使用这个接口接收服务器里所有的Update，与长轮询版的区别在于，它不会阻塞在那等待新消息，也适用于多实例并发调用。其它和长轮询版一致。

消息详情#

使用场景#

获取单条信息详情 Message

Uri#

Post: /api/bot/{bot token}/getMessage

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是此接口仅支持channel_id
message_idInteger是消息id

响应载体#

发普通消息#

使用场景#

可以发送一些文本消息，包括富文本和动态卡片. 成功后返回 Message 对象，目前该功能做了限制，可以联系运营开放

Uri#

Post: /api/bot/{bot token}/sendMessage

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
textString是发送的文本内容，1~150000个字节(包含空格和各种转义符)
descString是消息内容的描述，在fanbook的消息列表中，展示了最近的一些对话，包括群和私聊的，该内容展示在列表中每个对话。如果是简单文本，一般就是消息内容。如果是富文本或者活动卡片，可以是对该消息的一段描述。会影响私聊的外显信息。
parse_modeString可选开放平台解析消息的模式，如果是发送富文本或者是动态卡片必须设置为"Fanbook". 具体请查看 formatting options 的描述.
ephemeralBoolean可选消息是否是临时消息，发送临时消息时同时需指定users参数；临时消息的意思是该消息不会做持久化存储，也不会在多端设备上同步，清除手机缓存后，也看不到该消息了，同时该消息不能被表态。
usersArray of String可选当设置了ephemeral参数时，users表示发送给那些用户，此处填写用户的user_id, 如果填充为all（users:["all"]），表示发送给所有在线用户.
selectiveBoolean可选通过本参数可设置消息仅发送者和在消息中被 @ 提及的用户可见。在消息中 @ 用户请参考 在消息中提及用户或角色
reply_to_message_idInteger可选情况1：回复首条消息时，被引用消息的message_id字段；情况2：回复子消息时，被引用消息的quoteL1字段
reply_to_message_id_level_2Integer可选情况1：回复首条消息时，请置空；情况2：回复子消息时，被引用消息的message_id字段
reply_markupInlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply可选附加的接口选项. json格式化的对象，这些对象定义有内联键盘，自定义回复键盘，关于内联消息的定义可以参考API可用类型的说明, 或者参考telegram的说明，我们是对他们兼容的实现：inline keyboard, custom reply keyboard。
unreactiveInteger可选值为1表示不能对此消息进行表态，空值或者0表示可以表态
mentionsArray of String可选需要通知提醒的user id列表。需要和text字段里@用户一起设置
mention_rolesArray of String可选需要通知提醒的role id列表。需要和text字段里@角色一期设置

响应载体示例#

{    "ok": true,    "result": {        "message_id": 463992311181737984,        "date": 1675847275548,        "chat": {            "id": 423384907343****,            "guild_id": 0,            "type": "channel",            "channel_type": 3        },        "from": {            "id": 315058256093****,            "is_bot": true,            "first_name": "bot-255697422582284288-94",            "username": "1421563",            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0****.jpg"        },        "reply_to_message": null,        "text": "{\"notification\":\"任务达成\",\"data\":\"{  \\\"tag\\\": \\\"column\\\",  \\\"children\\\": [    {      \\\"tag\\\": \\\"container\\\",      \\\"padding\\\": \\\"12,8,12,8\\\",      \\\"width\\\": 1024,      \\\"backgroundColor\\\": \\\"e5f1ff\\\",      \\\"child\\\": {        \\\"tag\\\": \\\"text\\\",        \\\"data\\\": \\\"任务达成1\\\",        \\\"style\\\": {          \\\"color\\\": \\\"#198CFE\\\",          \\\"fontSize\\\": 16,          \\\"fontWeight\\\": \\\"medium\\\"        }      }    },    {      \\\"tag\\\": \\\"container\\\",      \\\"padding\\\": \\\"12\\\",      \\\"width\\\": 1024,      \\\"child\\\": {        \\\"tag\\\": \\\"markdown\\\",        \\\"overflow\\\": \\\"clip\\\",        \\\"textAlign\\\": \\\"left\\\",        \\\"style\\\": {          \\\"fontSize\\\": 15,          \\\"color\\\": \\\"#1F2329\\\"        },        \\\"data\\\": \\\"恭喜你完成每日发言，获得100积分\\\"      }    }  ]}\",\"come_from_name\":\" xiaotu的测试服务器\",\"type\":\"messageCard\",\"come_from_icon\":\"https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/circleIcon/2f897*****\"}",        "entities": []    }}

常用属性组合#

除了必填项之外，parse_mode通常为需要填写的参数，可以支持更多复杂text类型。但相反如果只是想发一句纯文本text，则不加此参数。

  1. 如果想该消息只被某些用户看到，需指定 ephemeral + users，如果users为"all"，则该消息为该频道下所有成员可见的临时在线消息。

  2. reply_to_message_id 和 reply_to_message_id_level_2 是当前消息引用的消息。

  3. 需要@用户时，text里有"${@!174372373544304640}"，同时mentions里面也需要填写该用户的ID。同理@角色需要在mention_roles里填写。

更多待补充

消息体中提及用户或角色#

通过 Fanbook 的文本标记语言，可实现通过 user_id 在消息内容中 @ 提及用户和角色，格式如下： 用户格式：

${@!174372373544304640} 恭喜签到成功

角色格式：

${@&174372373544304640} 恭喜签到成功

174372373544304640 是用户的 长ID 或 角色ID，在Fanbook客户端的渲染中，对应文本会被替换显示为用户的昵称或角色的名称

富文本格式#

消息：

{    "chat_id": 101726072105606324,    "text": "{\"type\":\"richText\",\"title\":\"签到成功\",\"document\":\"[{\\\"insert\\\":\\\"恭喜你签到成功\\\"}]\"}",    "parse_mode": "Fanbook"}

消息内容：

  • richText：指定本消息类型是富文本消息
  • title：富文本的标题
  • document：富文本的正文格式
{    "type": "richText",    "title": "「怪物猎人专服」签到送【怪猎盲盒手办】活动开启！",    "document": "[{\"insert\":\"点击下方链接参与\\nhttps://fanbook.mobi/UrKZ2FWU\\n\"},{\"insert\":{\"source\":\"https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/cf31fcb03a7cc7626dfd9dae997b9355.jpg\",\"width\":500.0,\"height\":500.0,\"_type\":\"image\",\"_inline\":false}},{\"insert\":\"\\n\\n\"},{\"insert\":{\"source\":\"https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/cf84df484f22238d664b9a5342d120b4.jpg\",\"width\":800.0,\"height\":800.0,\"_type\":\"image\",\"_inline\":false}},{\"insert\":\"\\n\"},{\"insert\":{\"source\":\"https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/4b445f53fdb567b38e4666bf2b2a47a4.jpg\",\"width\":750.0,\"height\":750.0,\"_type\":\"image\",\"_inline\":false}},{\"insert\":\"\\n\\n\\n\"}]"}

富文本的正式格式：

  • insert：代表一个内容节点，节点类型支持文本和图片
  • 换行：通过 \n 的文本节点可实现换行
[    {        "insert": "点击下方链接参与\nhttps://fanbook.mobi/UrKZ2FWU\n"    },    {        "insert": {            "source": "https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/cf31fcb03a7cc7626dfd9dae997b9355.jpg",            "width": 500.0,            "height": 500.0,            "_type": "image",            "_inline": false        }    },    {        "insert": "\n\n"    },    {        "insert": {            "source": "https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/cf84df484f22238d664b9a5342d120b4.jpg",            "width": 800.0,            "height": 800.0,            "_type": "image",            "_inline": false        }    },    {        "insert": "\n"    },    {        "insert": {            "source": "https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/4b445f53fdb567b38e4666bf2b2a47a4.jpg",            "width": 750.0,            "height": 750.0,            "_type": "image",            "_inline": false        }    },    {        "insert": "\n\n\n"    }]

发图片消息#

使用场景#

发送图片，成功则返回 Message 对象

Uri#

Post: /api/bot/{bot token}/sendPhoto

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
photoObject是待发送的图片. 图片的url地址，具体参考示例
widthInteger可选可以手动定义，会增加接口的性能
heightInteger可选可以手动定义，会增加接口的性能
reply_to_message_idInteger可选回复某条消息时，填写引用消息的message_id
reply_markupInlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply可选附加的接口选项. json格式化的对象，这些对象定义有内联键盘，自定义回复键盘，关于内联消息的定义可以参考API可用类型的说明, 或者参考telegram的说明，我们是对他们兼容的实现：inline keyboard, custom reply keyboard。

示例：

{    "photo":{        "Url":"http://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/afa1a29c055fc15eb9b6a8c3f88ddb54.jpeg"    },    "chat_id":239729082835664897}

发送带内联键盘的图片示例如下：

{    "photo":{        "Url":"http://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/afa1a29c055fc15eb9b6a8c3f88ddb54.jpeg"    },    "chat_id":239729082835664897,    "reply_markup":{        "inline_keyboard":[            [                {                    "text":"确定",                    "callback_data":"456"                }            ],            [                {                    "text":"取消",                    "callback_data":"123"                }            ]        ]    }}

比如全球行动绑定机器人的格式如下：

{    "photo":{        "Url":"http://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/afa1a29c055fc15eb9b6a8c3f88ddb54.jpeg"    },    "chat_id":239729082835664900,    "reply_markup":{        "inline_keyboard":[            [                {                    "text":"确定",                    "callback_data":"confirm#>{\"command\":\"confirm\",\"data\":{\"credit_apply\":{\"guild_id\":259248080753266688,\"user_id\":135398049852686336,\"status\":true,\"apply_data\":{\"server_id\":\"302\",\"pid\":\"3568780\"},\"updated_at\":1628066996,\"created_at\":1628066996,\"message_id\":263587296580730880},\"unbind\":{\"guild_id\":259248080753266688,\"user_id\":135398049852686336,\"unbind_times\":1,\"latest_unbind_time\":1627141034},\"username\":\"655690\",\"nickname\":\"Allen.Lee\"}}"                }            ],            [                {                    "text":"取消",                    "callback_data":"cancle#>{\"command\":\"cancle\",\"data\":{\"credit_apply\":{\"guild_id\":259248080753266688,\"user_id\":135398049852686336,\"status\":true,\"apply_data\":{\"server_id\":\"302\",\"pid\":\"3568780\"},\"updated_at\":1628066996,\"created_at\":1628066996,\"message_id\":263587296580730880},\"unbind\":{\"guild_id\":259248080753266688,\"user_id\":135398049852686336,\"unbind_times\":1,\"latest_unbind_time\":1627141034},\"username\":\"655690\",\"nickname\":\"Allen.Lee\"}}"                }            ]        ]    }}

响应载体#

{    "ok": true,    "result": {        "message_id": 463997178994491392,        "date": 1675848436124,        "chat": {            "id": 423384907343*****,            "guild_id": 0,            "type": "channel",            "channel_type": 3        },        "from": {            "id": 315058256093*****,            "is_bot": true,            "first_name": "bot-255697422582284288-94",            "username": "1421563",            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg"        },        "reply_to_message": null,        "text": "{\"type\":\"image\",\"url\":\"https://img2.huashi6.com/images/resource/thumbnail/2022/12/13/15245_5652012520.jpg?imageMogr2/quality/100/interlace/1/thumbnail/2000x%3E\",\"fileType\":\"image/jpeg\",\"width\":1600,\"height\":900}",        "entities": []    }}

发送通知#

使用场景#

发送一份通知

Uri#

Post: /api/bot/{bot token}/sendNotication

请求载体#

ParameterTypeRequiredDescription
channel_typeString是"1" : 未完成任务频道，"2" : 已完成任务频道
to_user_idString是发送给用户的user_id
contentString是任务内容
nonceString是本地雪花id

响应载体#

消息表态#

使用场景#

对某条消息进行表态

Uri#

Post: /api/bot/{bot token}/sendReaction

请求载体#

ParameterTypeRequiredDescription
user_idString是用户id
message_idString是对消息表态的消息id
channel_idString是频道id
emojiString可选表情包，需要进行url encode ，见下文详细描述
avatarString可选自定义表情

表态的emoji目前有以下这些：

"赞","掌声","好的","+1,"爱心","比心","完成","微笑","可爱","憨笑","呲牙","色","汗颜","斜眼笑","暗中观察","酷","大哭","害羞","飞吻","瞌睡","尴尬","666","碰拳","握手","抱拳","玫瑰","加油干","奥力给","厉害哦","庆祝","干杯","惊喜","灵光一闪","可怜","鼓掌","再见","恶心","叹气","快哭了","耶","哈欠","爱意","倒笑脸","裂开","衰","小恶魔","猪头","生病","委屈","闭嘴","捂脸哭","不看","不听","嘿哈","挖鼻孔","不说","烦躁","拥抱","捂嘴笑","吃瓜","疑惑","幽灵","扶额","举手","拜托","拒绝","生气","勾","不","对","叉","1","2","3","4","A","B","C","D"

响应载体#

修改消息#

使用场景#

使用该方法编辑消息文本，对于任务卡片、富文本和普通文本都适用，也使用内联键盘消息. 成功后会返回 Message 对象

Uri#

Post: /api/bot/{bot token}/editMessageText

请求载体#

ParameterTypeRequiredDescription
chat_idInteger可选如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
message_idInteger可选待编辑的消息ID
inline_message_idString可选如果chat_id和message_id未提供，则填写inline_message_id，目前不适用fanbook平台
textString是新的消息文本内容，1~102400个字节
parse_modeString可选解析消息的模式，参见上文提到 formatting options 以获取更详细的说明.
disable_web_page_previewBoolean可选禁用此消息中链接的链接预览，比如在消息中存储url链接，如果设置这个参数位TRUE，显示消息时则不解析这个链接地址
reply_markupInlineKeyboardMarkup可选json序列化的内联键盘 inline keyboard.
selectiveBoolean可选如果为 true, 禁用预览（即不显示)

响应载体#

修改内联键盘#

使用场景#

修改消息的内联键盘。成功则则返回 Message 对象

Uri#

Post: /api/bot/{bot token}/editMessageReplyMarkup

请求载体#

ParameterTypeRequiredDescription
chat_idInteger可选如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
message_idInteger可选待编辑的消息ID
inline_message_idString可选如果chat_id和message_id未提供，则填写inline_message_id，目前不适用fanbook平台
reply_markupInlineKeyboardMarkup可选json序列化的内联键盘 inline keyboard.

响应载体#

删除消息#

使用场景#

删除消息，注意以下几点： - 机器人可以删除私聊，频道里的消息； - 机器人如果是管理员，则可以删除任意的消息； - 机器人如果有删除消息的权限，则可以删除对应频道的任意消息； 成功则返回TRUE

Uri#

Post: /api/bot/{bot token}/deleteMessage

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是频道ID，私信消息请调用 获取私信会话
message_idInteger是消息ID

响应载体#

话题消息列表#

使用场景#

获取一条话题下的消息列表，默认一页100条。从最新开始拉，列表按时间倒序。

Uri#

Post: /api/bot/{bot token}/v2/quotes

请求载体#

ParameterTypeRequiredDescription
channel_idString是频道ID
quote_idString是话题被引用的第一条消息ID
message_idString否上一页的最后一条消息ID，作为分页

响应载体#

{    "ok": true,    "result": [        {            "message_id": "513618459800633344",            "user_id": "511819060564983808",            "guild_id": "390438216731197440",            "content": "{\"type\":\"text\",\"text\":\"https://bot-test.fanbook.mobi/mp/teamrank/rooms?fb_redirect&open_type=mp&debug&guild_id=189278210867855360\",\"contentType\":16}",            "quote_l1": null,            "quote_l2": null,            "time": 1687679071386        }    ]}

Pin消息#

使用场景#

使用该方法去pin某条消息，pin成功后，在pin的列表会现在该条消息。 该机器人必须具备pin消息和修改消息的权限。成功则返回true

Uri#

Post: /api/bot/{bot token}/pinChatMessage

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
message_idInteger是被pin的消息id
channel_idInteger是服务器的频道ID

响应载体#

UnPin消息#

使用场景#

unpin某条消息，unpin成功后，pin列表里删除该条消息，机器人必须具备pin消息和修改消息的权限，成功则返回true

Uri#

Post: /api/bot/{bot token}/pinChatMessage

请求载体#

ParameterTypeRequiredDescription
chat_idIntegerYes如果是发送到频道，则填写channel_id，如果是私信给某个用户，则需要调用getPrivateChat接口获取到chat_id
message_idIntegerYes被pin的消息id

响应载体#

交互：点击消息卡片#

使用场景#

触发消息卡片 点击 事件

Uri#

Post: /api/bot/{bot token}/interaction/message_card/click

请求载体#

ParameterTypeRequiredDescription
keyString是槽位
channel_idString是频道ID
message_idString是消息卡片ID
user_idString可选用户ID

响应载体#

交互：取消点击消息卡片#

使用场景#

触发 取消点击 事件

Uri#

Post: /api/bot/{bot token}/interaction/message_card/cancel_click

请求载体#

ParameterTypeRequiredDescription
keyString是槽位
channel_idString是频道ID
message_idString是消息卡片ID
user_idString可选用户ID

响应载体#

交互：自动获取槽位#

使用场景#

从服务台申请获取一个槽位，以触发点击事件

Uri#

Post: /api/bot/{bot token}/interaction/message_card/auto

请求载体#

ParameterTypeRequiredDescription
channel_idString是频道ID
message_idString是消息ID
maxnumber是最大槽位值，最大 50
user_idString可选用户ID

响应载体#

交互：获取消息卡片用户列表#

使用场景#

使用该消息可以发送一些文本消息，包括富文本和动态卡片. 成功后返回 Message 对象

Uri#

Post: /api/bot/{bot token}/message_card/list_users

请求载体#

ParameterTypeRequiredDescription
keyString是槽位
channel_idString是频道ID
message_idString是消息卡片ID
user_idString可选用户ID

响应载体#

响应会返回状态及如下数据:

response data:

ParameterTypeRequiredDescription
listArray是UserInfo列表

UserInfo:

ParameterTypeRequiredDescription
keyString是槽位
user_idString是用户ID

服务台#

服务台信息#

使用场景#

获取服务器的基本信息，返回Guild对象

Uri#

Post: /api/bot/{bot token}/guild

请求载体#

ParameterTypeRequiredDescription
user_idString是填充bot_id
guild_idString是服务器ID

响应载体#

查询用户列表#

使用场景#

分页查询获取服务器的成员列表

Uri#

Post: /api/bot/{bot token}/v2/guild/members

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务台 ID
channel_idString是服务器频道id，服务器里有多个频道，不同频道的成员列表不一定完全一样，比如私密频道。
user_idString是用户id，必须在该服务器里
rangesArray[]是分页结构，比如："ranges":[{"start":0, "end":99}]
transactionString可选请求的事物ID，唯一标识一次请求，主要是用于调试
{    "guild_id":"239729082814693376",    "channel_id":"0",    "user_id":"91142882827837440",    "ranges":[{"start":0, "end":99}],    "transaction":"kbqyFzvOBkgo"}

响应载体#

{    "ok": true,    "result": {        "ops": [            {                "range": [                    0,                    10                ],                "op": "SYNC",                "items": [                    {                        "Group": {                            "id": "239729082827276288",                            "name": "管理员",                            "count": 1                        }                    },                    {                        "User": {                            "user_id": "86655584392323072",                            "nickname": "allen.lee004",                            "username": "1266917",                            "avatar": "https://fb-cdn.fanbook.mobi/fanbook/app/files/service/headImage/131108f97ec49beeba086ab7ffdcdd78",                            "roles": [                                {                                    "id": "239729082827276288",                                    "name": "管理员"                                }                            ]                        }                    },                    {                        "User": {                            "user_id": "194290421168340992",                            "nickname": "noisy",                            "username": "111126",                            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg",                            "roles": [                                {                                    "id": "239729082827276288",                                    "name": "管理员"                                }                            ]                        }                    },                    {                        "User": {                            "user_id": "242536260613177344",                            "nickname": "圈子机器人",                            "username": "1819241",                            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg",                            "roles": [                                {                                    "id": "239729082827276288",                                    "name": "管理员"                                }                            ]                        }                    },                    {                        "User": {                            "user_id": "239730861589659648",                            "nickname": "签到测试",                            "username": "1135624",                            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg",                            "roles": [                                {                                    "id": "239729082827276288",                                    "name": "管理员"                                }                            ]                        }                    },                    {                        "Group": {                            "id": "256427206794805248",                            "name": "新角色1",                            "count": 1                        }                    },                    {                        "User": {                            "user_id": "86490735033065472",                            "nickname": "dragon/2046",                            "username": "4551735",                            "avatar": "https://xms-dev-1251001060.cos.ap-guangzhou.myqcloud.com/x-project/user-upload-files/d05248587bbdbbac895ab558536ba355",                            "roles": [                                {                                    "id": "256427206794805248",                                    "name": "新角色1"                                }                            ]                        }                    },                    {                        "Group": {                            "id": "239729082814693376",                            "name": "成员",                            "count": 1                        }                    },                    {                        "User": {                            "user_id": "251234133928312832",                            "nickname": "Fan-bot",                            "username": "1156284",                            "avatar": "https://fb-cdn.fanbook.mobi/fanbook/app/files/chatroom/image/32681468792f5f8047cb8fa108bf2198.jpg"                        }                    },                    {                        "User": {                            "user_id": "136762723340914688",                            "nickname": "机器人管家",                            "username": "919679",                            "avatar": "https://fanbook-1251001060.cos.ap-guangzhou.myqcloud.com//fanbook/app/files/chatroom/image/0de40d70f3baf11720736a7c51cc57da.jpg"                        }                    },                    {                        "User": {                            "user_id": "258501794529804288",                            "nickname": "机器好人",                            "username": "1207320",                            "avatar": "https://fb-cdn.fanbook.mobi/x-project/user-upload-files/d42ca330d93d88e0e7c19e2b2fe42fb5.jpg"                        }                    }                ]            }        ],        "online_count": 0,        "member_count": 8,        "guild_count": 8,        "item_count": 11,        "guild_id": "239729082814693376",        "channel_id": "0",        "channel_pub_ids": [            "254598459024211968",            "261483161303646208",            "239729082835664897",            "261486700847431680",            "239729082835664896"        ],        "groups": [            {                "id": "239729082814693376",                "name": "成员",                "count": 3            },            {                "id": "256427206794805248",                "name": "新角色1",                "count": 1            },            {                "id": "239729082827276288",                "name": "管理员",                "count": 4            }        ]    }}

成员列表会按照角色进行分段显示，groups表示角色信息，id为角色的id，name表示角色名字，count表示该角色下用户的数量，当用户有多个角色时，是按照角色的position进行排序的

角色查询用户列表#

使用场景#

通过这个方法可获取服务台的角色列表，成功后返回 ChatMember 数组

Uri#

Post: /api/bot/{bot token}/getRoleMembers

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
role_idInteger是角色 ID
sizeInteger否上限500条
last_idInteger否作为分页的用户 ID，不填默认第一页

响应载体#

昵称查询用户列表#

使用场景#

按照用户昵称搜索服务台用户，成功后返回 ChatMember 数组。需注意，目前仅支持50个上限

Uri#

Post: /api/bot/{bot token}/searchGuildMember

请求载体#

ParameterTypeRequiredDescription
guild_idIntegerYes服务台 ID
queryStringYes搜索关键词，使用昵称查询，支持模糊查询

响应载体#

短ID查询用户#

使用场景#

使用用户 username 搜索服务台用户，成功后返回 ChatMember 数组

Uri#

Post: /api/bot/{bot token}/searchGuildMemberByName

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
usernameArray[String]是由fanbook 短id组成的数组

响应载体#

覆盖角色#

使用场景#

可设置服务台用户的角色，此方法为覆盖式，成功后返回 True 数组

Uri#

Post: /api/bot/{bot token}/setMemberRoles

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
user_idInteger是用户 ID
rolesArray[Integer]是角色 ID 数组

响应载体#

修改角色#

使用场景#

可设置服务台用户的角色，此方法为修改式，成功后返回 True 数组

Uri#

Post: /api/bot/{bot token}/v2/setMemberRoles

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
user_idInteger是用户 ID
rolesArray[Integer]是角色 ID 数组
operationString是add表示追加角色，del表示删除角色

响应载体#

用户是否在服务台内#

使用场景#

校验某用户是否在服务台里

Uri#

Post: /api/bot/{bot token}/guild/existsMember

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务台 ID
member_idString可选可指定 member_id, 如果没有则默认为查询该机器人自己是否在该服务器。

响应载体#

{  "ok": true,  "result": {    "exists": false  }}

禁言用户#

使用场景#

以秒为单位禁言用户，需要bot有禁言权限

Uri#

Post: /api/bot/{bot token}/forbidUserSpeaking

请求载体#

ParameterTypeRequiredDescription
target_uidString是目标用户 id
target_guild_idString是目标服务器 id
duration_in_secondInt是禁言时长（以秒为单位)

响应载体#

移除聊天对象#

使用场景#

从服务器里踢出某个成员，机器人必须拥有管理服务器的权限

Uri#

Post: /api/bot/{bot token}/kickChatMember

请求载体#

ParameterTypeRequiredDescription
chat_idInteger可选频道 ID，chat_id 和 guild_id 至少传一个
guild_idInteger可选服务台 ID，chat_id 和 guild_id 至少传一个
user_idInteger是用户的user_id
until_dateInteger可选持续多长时间用户才能再次加入服务器的时间，是个unix时间戳，以秒为单位，（该功能目前尚未实现，预留的字段）

响应载体#

服务器emoji列表#

使用场景#

查看当前服务器表情，成功则返回一组GuildEmoji对象

Uri#

Get: /api/bot/{bot token}/guild/emoji

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID

响应载体#

邀请码列表#

使用场景#

获取服务器的邀请码列表

Uri#

Post: /api/bot/{bot token}/invite/guildList

请求载体#

ParameterTypeRequiredDescription
guild_idString是有权限的服务台id
sizeString否每页返回多少条邀请码记录
list_idString否服务端返回的list_id，使用该list_id可以请求下一页

响应载体#

邀请码详情#

使用场景#

查看邀请码的详情

Uri#

Post: /api/bot/{bot token}/invite/codeInfo

请求载体#

ParameterTypeRequiredDescription
cString是邀请码

响应载体#

查询用户实名验证#

使用场景#

获取某用户是否已经身份证验证成功，成功后返回的data域的authenrited字段表明认证结果，true表示已经验证，false表示未认证。失败则会返回错误码

Uri#

Get: /api/bot/{bot token}/user/human_authentication

请求载体#

ParameterTypeRequiredDescription
user_idString是用户的user_id

响应载体#

筛选用户有效服务器#

使用场景#

有些场景，需要确认用户是否存在于目标服务器内，可以调用该方法

Uri#

Post: /api/bot/{bot token}/v2/checkUserGuilds

请求载体#

ParameterTypeRequiredDescription
user_idi64是用户的Fanbook id
guildsArray [i64]是需要校验的服务器ID数组

响应载体#

频道#

频道列表#

使用场景#

获取服务器的频道列表，返回Channel数组

Uri#

Post: /api/bot/{bot token}/channel/list

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID

响应载体#

{    "ok": true,    "result": [        {            "channel_id": "413582158565736448",            "guild_id": "390438216731197440",            "name": "语音",            "type": 1,            "user_limit": 10,            "permission_overwrites": [                {                    "id": "390438216852832256",                    "action_type": "role",                    "allows": 1024,                    "deny": 0                },                {                    "id": "395466988350078976",                    "action_type": "user",                    "allows": 2098177,                    "deny": 0                }            ]        }    ]}

频道消息列表#

使用场景#

使用该消息可以发送一些文本消息，包括富文本和动态卡片. 成功后返回 Message 对象列表，按时间倒序排序

Uri#

Post: /api/bot/{bot token}/message/getList

请求载体#

消息体内容类型(Content-Type) : application/x-www-form-urlencoded

ParameterTypeRequiredDescription
channel_idString是频道ID
sizeString可选当前获取的消息个数，最大100个
message_idString可选获取消息列表的基准消息的消息ID，使用默认before模式时，可以用上一次获取的最后一条内容message id作为该基准消息
behaviorString可选查询消息列表时message_id参数指定消息的之前的消息还是之后的消息，before表示message_id指定消息的之前的消息，after表示之后的消息；默认取值before。

响应载体#

{    "status": true,    "code": 1000,    "message": "1000",    "desc": "成功",    "request_id": "645c84e796b637.09869467",    "data": [        {            "channel_id": "413613404125659136",            "message_id": "495447611042430976",            "content": "{\"notification\":\"正好耿耿\",\"data\":\"{  \\\"tag\\\": \\\"container\\\",  \\\"width\\\": 1024,  \\\"child\\\": {    \\\"tag\\\": \\\"column\\\",    \\\"children\\\": [      {        \\\"tag\\\": \\\"container\\\",        \\\"width\\\": 1024,        \\\"backgroundColor\\\": \\\"e5f1ff\\\",        \\\"child\\\": {          \\\"tag\\\": \\\"text\\\",          \\\"data\\\": \\\"活动通知\\\",          \\\"style\\\": {            \\\"color\\\": \\\"#198CFE\\\",            \\\"fontSize\\\": 16,            \\\"fontWeight\\\": \\\"medium\\\"          }        },        \\\"padding\\\": \\\"12,10,12,6\\\"      },      {        \\\"tag\\\": \\\"divider\\\"      },      {        \\\"tag\\\": \\\"container\\\",        \\\"width\\\": 1024,        \\\"child\\\": {          \\\"tag\\\": \\\"markdown\\\",          \\\"data\\\": \\\"你在【正好耿耿】中的邀请奖励1.00元已到账\\\",          \\\"style\\\": {            \\\"color\\\": \\\"#000000\\\",            \\\"fontSize\\\": 17,            \\\"fontWeight\\\": \\\"medium\\\"          }        },        \\\"padding\\\": \\\"12,8,12,0\\\"      },      {        \\\"tag\\\": \\\"container\\\",        \\\"width\\\": 1024,        \\\"child\\\": {          \\\"tag\\\": \\\"markdown\\\",          \\\"data\\\": \\\"请到【我的-我的资产-我的收入】查看\\\",          \\\"style\\\": {            \\\"color\\\": \\\"#000000\\\",            \\\"fontSize\\\": 17,            \\\"fontWeight\\\": \\\"medium\\\"          }        },        \\\"padding\\\": \\\"12,8,12,0\\\"      }    ]  }}\",\"come_from_name\":\"shuhaobot\",\"type\":\"messageCard\",\"come_from_icon\":\"https://fb-cdn.fanbook.mobi/fanbook/app/files/service/headImage/7be6fb897780dfa493446f5926bf6a4f\"}",            "user_id": "463238807253155840",            "quote_l1": null,            "quote_l2": null,            "guild_id": "390438216731197440",            "reactions": [],            "recall": null,            "pin": "0",            "nonce": "495447606470774784",            "mentions": null,            "mention_roles": null,            "mention_everyone": null,            "reply_markup": null,            "message_card": null,            "deleted_user": null,            "deleted": null,            "extra_data": null,            "time": 1683346803445,            "recalled": 0,            "author": {                "nickname": "乖乖",                "username": "10346643",                "avatar": "https://fanbook-gamescluster-1251001060.cos.ap-shanghai.myqcloud.com/open-fanbook/dev/BotAvatar-8ddbe3e1aaa1d95f707a52b32357af2f.jpg?v=1678848944000",                "avatar_nft": null,                "bot": true            },            "member": {                "nick": null,                "roles": [                    "462126193571790848",                    "486881599879643136"                ],                "guild_card": null            }        }    ]}

修改频道#

使用场景#

编辑频道的基本信息，基于普通频道和群

Uri#

Post: /api/bot/{bot token}/channel/edit

请求载体#

修改群（group dm channel）对象，则请求参数如下

ParameterTypeRequiredDescription
channel_idString是群 ID
user_idString是修改频道的用户的user_id，如果是机器人则填充bot_id
nameString可选群的名称
iconString可选群的头像

如果是服务器的频道，则请求参数如下：

ParameterTypeRequiredDescription
channel_idString是频道 ID
user_idString是修改频道的用户的user_id，如果是机器人则填充bot_id
guild_idString是服务器ID
nameString可选频道名称
topicString可选频道主题
parent_idString可选频道的分类ID
iconString可选频道图标

响应载体#

获取私信会话#

使用场景#

可得到与用户的私聊会话信息，成功后返回 Chat 数组

Uri#

Post: /api/bot/{bot token}/getPrivateChat

请求载体#

ParameterTypeRequiredDescription
user_idInteger是用户 ID

响应载体#

获取频道成员#

使用场景#

获取频道/服务器的成员. 成功则返回 ChatMember 对象

Uri#

Post: /api/bot/{bot token}/getChatMember

请求载体#

ParameterTypeRequiredDescription
chat_idInteger是服务台频道 ID
guild_idInteger是服务台 ID
user_idInteger是用户 ID

响应载体#

角色#

角色列表#

使用场景#

通过这个方法可获取服务台的角色列表，成功后返回 GuildRole 数组

Uri#

Post: /api/bot/{bot token}/getGuildRoles

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
last_idInteger可选上一页的最后一个id，不填则默认第一页

响应载体#

创建角色(身份组)#

使用场景#

创建服务器角色，返回GuildRole对象

Uri#

Put: /api/bot/{bot token}/guild/role

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID
nameString是频道名称
mentionablebool可选是否可被@
hoistbool可选角色是否应在侧边栏中单独显示
colorInteger可选角色显示的颜色

响应载体#

编辑角色#

使用场景#

修改服务器角色

Uri#

Patch: /api/bot/{bot token}/v2/guild/role

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID
idString是角色ID，若要编辑 全体成员 ，请填服务器ID
nameString可选角色名称
permissionsInteger是角色的权限值，参照[GuildRole](Bot API/API可用类型#guildrole)定义
mentionablebool可选是否可被@
hoistbool可选角色是否应在侧边栏中单独显示
colorInteger可选角色显示的颜色

响应载体#

删除角色#

使用场景#

删除服务器角色

Uri#

Delete: /api/bot/{bot token}/v2/guild/role

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID
idString是角色id

响应载体#

圈子#

圈子是Fanbook频道里信息的另一种承载频道，可以类比为服务器的朋友圈，或者分享频道

圈子列表#

使用场景#

圈子动态列表，返回CirclePost对象列表

Uri#

Post: /api/bot/{bot token}/circle/postList

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务器ID
channel_idString是圈子频道ID
topic_idString可选圈子主题ID
sizeString可选每页数量
list_idString可选分页标识，每一次请求会返回一个新的list_id，可以作为下次请求的参数做分页
wdString可选搜索关键字
has_videoString可选是否包含视频

响应载体#

圈子详情#

使用场景#

获取具体某个圈子详情

Uri#

Post: /api/bot/{bot token}/circle/detail

请求载体#

ParameterTypeRequiredDescription
post_idString是圈子动态的ID
channel_idString可选圈子动态当前频道的ID
topic_idString可选圈子动态的主题（类别）ID

响应载体#

圈子主页详情#

使用场景#

获取服务器圈子主页的详情信息

Uri#

Post: /api/bot/{bot token}/v2/circle/info

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务器 ID

响应载体#

圈子表态列表#

使用场景#

获取圈子动态的表态列表，支持分页获取，list_id是上一页最后一条表态的reaction_id

Uri#

Post: /api/bot/{bot token}/v2/circle/reactionList

请求载体#

ParameterTypeRequiredDescription
post_idString是圈子动态的ID
list_idString否圈子动态的表态列表的最后一条记录的reaction_id
sizeInteger否当前这一页返回的数量

响应载体#

圈子评论列表#

使用场景#

获取圈子动态的评论列表，支持分页拉取

Uri#

Post: /api/bot/{bot token}/v2/circle/commentList

请求载体#

ParameterTypeRequiredDescription
post_idString是圈子动态的ID
list_idString否圈子动态的表态列表的最后一条记录的comment_id
sizeString否当前这一页返回的数量
channel_idString是圈子动态当前所属的频道
since_idInteger否若指定此参数，则返回ID比当前list_id晚的评论，否则返回早于当前的评论

响应载体#

圈子评论回复列表#

使用场景#

获取圈子动态的评论回复列表，支持分页获取，成功则返回CirclePostComment对象

Uri#

Post: /api/bot/{bot token}/v2/circle/commentReplyList

请求载体#

ParameterTypeRequiredDescription
post_idString是圈子动态的ID
list_idString否圈子动态的表态列表的最后一条记录的comment_id
sizeString否当前这一页返回的数量
comment_idString是圈子动态的评论的ID

响应载体#

删除圈子#

使用场景#

使用该消息可以发送一些文本消息，包括富文本和动态卡片. 成功后返回 Message 对象

Uri#

Del: /api/bot/{bot token}/v2/circle/postDelete

请求载体#

ParameterTypeRequiredDescription
post_idString是圈子动态ID
channel_idString是圈子频道ID
topic_idString是圈子主题ID
reasonString否删除原因

响应载体#

圈子表态用户列表#

使用场景#

获取圈子帖子的表态用户列表 ChatMember

Uri#

Post: /api/bot/{bot token}/getCircleReactionList

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务台 ID
post_idString是圈子 ID
list_idString可选最後的 list_id，请求一下页时传过来，如果是留言这个是最後一条记录的留言ID，如果是点赞，是例表最後一条点赞ID
sizeunsigned int可选用户列表分页后，每页用户数量

响应载体#

圈子评论用户列表#

使用场景#

获取圈子帖子的评论用户列表 ChatMember

Uri#

Post: /api/bot/{bot token}/getCircleCommentList

请求载体#

ParameterTypeRequiredDescription
guild_idString是服务台 ID
post_idString是圈子 ID
list_idString可选最後的 list_id，请求一下页时传过来，如果是留言这个是最後一条记录的留言ID，如果是点赞，是例表最後一条点赞ID
sizeunsigned int可选用户列表分页后，每页用户数量

响应载体#

勋章/卡槽#

获取用户勋章信息#

使用场景#

返回服务台内指定用户的勋章数据

Uri#

Post: /api/bot/{bot_token}/getGuildCredit

请求载体#

ParameterTypeRequiredDescription
guild_idInteger是服务台 ID
user_idInteger是用户 ID

响应载体#

设置单个勋章#

使用场景#

为服务台用户或者是群用户设置服务台荣誉数据，一个用户可以有多份荣誉数据，使用card_id唯一标识，成功后返回 True

Uri#

Put: /api/bot/{bot_token}/v2/guild/credit

请求载体#

ParameterTypeRequiredDescription
chat_idInteger可选群的channel_id，chat_id 和 guild_id 至少传一个
guild_idString可选服务台guild_id，chat_id 和 guild_id 至少传一个
user_idString是用户 ID
card_idString是该勋章数据对应的卡片ID，10个字节以上，唯一标识guild_credit，建议使用uuid或者其它ID生成算法，如果是更新或者删除荣誉数据，card_id必须与之前设置的card_id一样。
guild_creditGuildCredit是新的荣誉数据

响应载体#

删除个人勋章#

使用场景#

为服务台用户或者是群用户清除服务台荣誉数据，成功后返回 True

Uri#

Del: /api/bot/{bot_token}/v2/guild/credit

请求载体#

ParameterTypeRequiredDescription
chat_idInteger可选群的channel_id，chat_id 和 guild_id 至少传一个
guild_idString可选服务台guild_id，chat_id 和 guild_id 至少传一个
user_idString是用户 ID
card_idString是该勋章数据对应的卡片ID，10个字节以上，唯一标识guild_credit，建议使用uuid或者其它ID生成算法，如果是更新或者删除荣誉数据，card_id必须与之前设置的card_id一样。

响应载体#