接入指南

机器人账号接入

创建个人机器人、申请权限,并通过个人 API 和事件接口处理消息。

机器人使用独立账号发布内容和发送回复。资源、帖子与消息显示机器人的身份,公开主页标明其所有者。个人用户可在网站设置的开放中心创建和管理自己的机器人;官方通知账号另行管理。

创建与授权

  1. 在开放中心创建机器人并编辑展示资料、头像与简介。
  2. 申请所需的权限和全站指令。每次申请提交完整的权限与指令清单;审核期间,已有的生效授权继续有效。
  3. 授权生效后,为机器人创建 PAT,勾选该令牌实际需要的 scope。令牌明文只显示一次。

资源、帖子、本人资料和组织的 14 项普通个人 API 权限默认都需要审核,包括读取权限。私信与房间事件权限各有策略;平台可将权限设置为自动批准、需要审核或禁用。生效授权、令牌 scope、内容所有权及操作时的账号状态会共同决定一次调用能否成功。策略禁用或账号停用会阻断已有授权。

机器人 PAT 只能代表该机器人,不能创建网站会话,也不能访问后台或媒体控制。使用普通个人 API 时,请参照个人 API中每项操作的 scope 与参数;机器人调用同一路径,资源、帖子和组织的归属由机器人身份决定。人工账号的 PAT 或 OAuth access token 不能代替机器人 PAT 调用机器人事件接口。

房间指令

机器人的指令清单在全站统一登记,房间管理者决定在自己的房间启用哪些指令。@handle 查服 参数 或有效的开头结构化提及需要机器人提及权限;无需提及的 /查服 参数 需要另外申请房间指令权限,默认进入审核。指令名称精确匹配,且可配置最少和最多参数数量。私聊由用户先发起,机器人只能对收到的事件回复,不能主动私信尚未与其互动的用户。

无 @ 触发权限随完整指令清单申请,管理员可逐条核准哪些指令能无需 @ 触发;未核准的指令仍可按提及权限使用。房间管理者仍需逐条选择本房间启用的指令。

公开机器人目录支持按名称或账号标识搜索,每次返回最多 20 个机器人;继续查询时传入上次响应的 next_cursor,搜索词必须保持一致。目录接口单独限制每分钟最多 20 次请求。房间管理者仍须在房间内明确启用机器人及可用指令。

接收事件和回复

完整字段、三类事件示例、TypeScript 消费代码与断线恢复见机器人事件与回复。

机器人事件参考提供 GET /v1/bots/me/events 和 POST /v1/bots/me/replies。两者使用机器人 PAT 的 bot:events:read;回复时还会再次检查该事件对应的私信或房间回复权限。下面的地址仅为本地示例,实际地址以 bots.json 中的服务地址为准。

curl 'http://127.0.0.1:4520/v1/bots/me/events?after=0&limit=50' \
  -H 'Authorization: Bearer <bot-pat>'

按返回的 next_after 保存消费位置,重启后继续补取。事件中的 event_id 可用于回复;action_key 由机器人为本次动作稳定生成。同一机器人、事件和 action_key 只以首次提交为准:即使后续提交的 content 不同,也会返回首次发送的 message_id(duplicate: true),不会修改或再次发送消息。幂等重试仍须通过当前资格复核;每个事件最多接受 5 个新的回复键,不同业务动作使用不同键。

机器人事件及其回复幂等记录的保留期为 90 天,后台会分批清理到期记录。清理后不能再用旧 event_id 回复;聊天消息不受影响,事件序号也不会重置。因此客户端应持续保存 next_after,不要依赖从零开始重新获取全部历史事件。

curl -X POST 'http://127.0.0.1:4520/v1/bots/me/replies' \
  -H 'Authorization: Bearer <bot-pat>' \
  -H 'Content-Type: application/json' \
  --data '{"event_id":"<event-id>","action_key":"lookup-1","content":"服务器在线"}'

可连接 wss://<API 域名>/v1/bots/me/events/stream 接收事件变化提示。WebSocket 只推送 {"event":"bot_events_changed"},不包含消息正文;建立连接和每次重连后仍需调用 HTTP 接口补取,运行期间也应定期补取。连接使用 Authorization: Bearer <bot-pat> 请求头,不在 URL 中放令牌。网页原生 WebSocket 不能设置该请求头,宜由可控制握手请求头的服务端客户端连接。

这些接口不使用 Cookie。Webhook 的订阅管理仍在网站同源接口下使用 Cookie、CSRF 和二次验证;资源发布事件仍由现有投递服务发送,与机器人事件 WebSocket 是两种不同通道。