自定义 BOT 开发 Bot API 入门指南

为什么要开发自定义 BOT

内置 BOT 能覆盖大部分常规需求，但遇到以下场景时，就需要自定义 BOT：

连接外部系统（电商、CRM、课程平台）
复杂的活动工作流（报名 → 审核 → 分组 → 发放奖励）
定制化的成员管理（如根据购买记录自动分配角色）
社区特有的自动化需求（如每日自动整理 FAQ）

开发前置条件

基本的编程能力（Python / Node.js / Go 均可）
一台可访问公网的服务器（或用 serverless 平台如 Vercel / Cloudflare Workers）
一个 Fanbook 账号（用来创建应用和获取 Token）

开发流程四步走

第一步：在开发者平台创建应用

访问 Fanbook 开发者平台：open.fanbook.mobi
登录后进入「应用管理」
点击「新建应用」，填写应用名称和描述
创建完成后，在应用详情页点击「添加机器人」
系统会为你生成一个 Bot Token——务必妥善保管，不要泄露

第二步：理解 Bot API 基础

API 地址格式： POST https://a1.fanbook.cn/api/bot/{bot token}/{api}

大部分接口是 POST 请求
请求体支持 application/json、application/x-www-form-urlencoded、multipart/form-data
响应是 JSON 格式，包含 ok 字段表示成功与否

第三步：写第一个 BOT

以下用 Python + requests 库实现一个最简单的「回声 BOT」——有人发消息它就回复同样的内容。

import requests

BOT_TOKEN = "你的 Bot Token"
BASE_URL = f"https://a1.fanbook.cn/api/bot/{BOT_TOKEN}"

# 获取 BOT 自身信息
def get_me():
    resp = requests.get(f"{BASE_URL}/getMe")
    return resp.json()

# 发送消息到频道
def send_message(chat_id, text):
    resp = requests.post(
        f"{BASE_URL}/sendMessage",
        json={
            "chat_id": chat_id,
            "text": text
        }
    )
    return resp.json()

if __name__ == "__main__":
    info = get_me()
    print(f"BOT 名称：{info['result']['username']}")

注意： 这只是一个最小化示例。真正能实时接收消息的 BOT 需要长轮询（Long Polling） 或 WebSocket 来监听新消息事件。

第四步：部署和运行

本地开发： 在自己电脑上运行测试
生产部署： 放到公网服务器上，用 systemd / PM2 / Docker 保持进程常驻
Serverless： 部分平台支持 serverless 部署（如 Cloudflare Workers），但需要自建消息轮询机制

核心 API 速查

方法	端点	说明
Get	`/getMe`	获取 BOT 信息（含 User Token）
Post	`/sendMessage`	发送消息到频道或私聊
Post	`/channel/list`	获取服务器的频道列表
Post	`/invite/guildList`	获取邀请码列表
Post	`/searchGuildMemberByName`	按名称搜索成员
Post	`/getPrivateChat`	获取私聊频道 ID

完整 API 文档： 访问 Fanbook 开发者平台 open.fanbook.mobi 查看。

消息接收机制

方式一：长轮询（推荐入门）

定期（每 1~2 秒）调用获取新消息的 API，有新消息就处理，没有就等待。

import time

while True:
    new_messages = poll_new_messages()  # 伪代码
    for msg in new_messages:
        handle_message(msg)  # 处理消息
    time.sleep(1)

优点： 简单、无需 WebSocket 连接管理缺点： 有 1~2 秒延迟、有额外 API 调用开销

方式二：WebSocket

Bot API 支持 WebSocket 连接，实时推送新消息事件。Bot 通过 /getMe 还会获得一个 User Token，用来建立 WebSocket 连接。

优点： 实时、低延迟、API 调用少缺点： 连接管理更复杂、断线重连需要自己处理

机器人管家

Fanbook 提供了「机器人管家」——一个特殊的 BOT，可以帮助你管理其他 BOT：

创建新 BOT（自动生成 Token）
编辑 BOT 设置
管理 BOT 的隐私模式（接收哪些消息）
查看 BOT 列表

隐私模式

重要配置： 机器人可以设置「隐私模式」——

开启隐私模式： BOT 只接收被 @ 或直接发给它的消息，不接收频道里所有消息
关闭隐私模式： BOT 接收频道里的所有消息

建议： 默认开启隐私模式，在确实需要监听所有消息的场景（如敏感词自动回复）才关闭。关闭隐私模式会让 BOT 接收大量无关消息，增加 API 调用量和服务器负载。

常见开发坑

Bot Token 泄露

Token 等于 BOT 的所有权限。绝对不要把 Token 硬编码在公开仓库里，用环境变量或密钥管理服务存储。

API 限流

Bot API 有调用频率限制（具体数值以官方文档为准）。过于频繁的调用可能被临时封停，建议在代码里做调用间隔控制。

频道权限

BOT 要在某个频道发消息，需要它（或其所有者账号）在该频道有 SEND_MESSAGES 权限。别忘了给 BOT 角色配置好频道权限。

长轮询的偏移量

用长轮询获取消息时，需要记录最后一条消息的 ID，下次从那个位置开始拉取，避免重复处理。