API 鉴权 Bot Token User Token WebSocket 连接

两种令牌

Fanbook Bot API 使用两种令牌进行身份验证，分别用于不同的场景：

Bot Token

获取方式

在机器人管家创建新 BOT 时自动生成。只会显示一次，请立即保存！

格式

Bot Token 的格式通常是一串较长的加密字符串，类似：

2556974225:ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

实际格式以官方生成的为准，上面只是示意。

使用方式

放在 API URL 的路径中：

POST https://a1.fanbook.cn/api/bot/{你的BotToken}/sendMessage

重置

如果怀疑 Token 泄露，可以在机器人管家里面重置 Token。重置后旧 Token 立即失效。

安全红线

• 绝对不要把 Bot Token 硬编码在公开仓库（如 GitHub）里
• 绝对不要把 Token 分享给他人
• 用环境变量或密钥管理服务存储
• 如果需要部署到服务器，用 .env 文件或云服务商的密钥管理

User Token

获取方式

调用 /getMe 端点的响应中会返回 user_token 字段。这个 Token 用于 WebSocket 连接和 GraphQL API。

使用方式

放在 HTTP 请求的 Header 中：

usertoken: {你的UserToken}

注意事项

• User Token 有有效期，过期后需要重新调用 /getMe 获取新的
• Bot Token 是长期的（直到手动重置），User Token 是短期的
• 两者配合使用：Bot Token 用于大多数 REST API，User Token 用于 WebSocket 和 GraphQL

鉴权流程

1. 创建 BOT → 获得 Bot Token
2. 用 Bot Token 调用 /getMe (GET)
   → 响应中包含 BOT 信息 + user_token
3. 用 Bot Token 调用大多数 Bot API 端点
4. 用 User Token 建立 WebSocket 连接（接收消息推送）
   → 或调用 GraphQL API
5. User Token 过期后，回到第 2 步重新获取

WebSocket 连接

用途

Bot API 有两种消息接收方式：长轮询（BOT 开发入门 已介绍）和 WebSocket。

WebSocket 的优势：

• 实时推送——新消息立即到达，无需等待
• 更低延迟——毫秒级 vs 长轮询的秒级
• 更少 API 调用——不需要每秒发起一次轮询请求

连接流程（以公开信息为准）

1. 调用 /getMe 拿到 user_token 和 WebSocket URL（如果 API 返回了）
2. 用 WebSocket 客户端连接 WebSocket URL
3. 在连接的认证阶段传入 user_token
4. 成功连接后，服务器开始推送事件（新消息、成员加入等）
5. 断线后需要自动重连，并在重连时重新用 user_token 认证

Python WebSocket 示例（概念性）

import websockets
import asyncio

async def main():
    uri = "wss://..."  # WebSocket 地址（从 API 获取）
    user_token = "..."  # 从 /getMe 拿到

    async with websockets.connect(uri) as ws:
        # 认证（具体格式以官方文档为准）
        await ws.send(user_token)

        # 接收事件推送
        async for event in ws:
            data = json.loads(event)
            # 处理消息事件、成员事件等
            print(data)

asyncio.run(main())

注意： WebSocket 的具体连接地址和认证协议以官方最新文档为准，上面只是示意性代码。

GraphQL API 鉴权

GraphQL API（用于机器人管理功能如更新 BOT 信息）需要在请求 Header 中携带 User Token：

POST https://a1.fanbook.cn/api/bot/console
Header: usertoken: {你的UserToken}
Content-Type: application/json

Body:
{
  "query": "mutation ..."
}

安全最佳实践总结

OAuth？

目前（以公开 API 文档为准）Fanbook Bot API 主要使用 Token 鉴权，没有看到完整的 OAuth 2.0 授权流程。如果官方后续开放 OAuth，应以最新文档为准。