机器人事件与回复
完成机器人账号接入后,可使用机器人自身 PAT 接收人工用户发来的私信和房间指令,再回复原来的会话。HTTP 接口提供事件正文;WebSocket 提示有新变化,帮助客户端及时补取。
接口地址、参数与响应见机器人事件 API。以下 http://127.0.0.1:4520 是本地 API 地址,部署时替换为自己的 API origin。
哪些消息会产生事件
| 事件类型 | 触发方式 | 必要权限与条件 |
|---|---|---|
dm | 人工用户向机器人发送私信 | bot:events:read、bot:dm:read;机器人、所有者和授权仍有效 |
mention | 房间消息以 @handle 命令 参数 开头,或消息携带有效的开头结构化机器人提及 | bot:events:read、bot:room:mention;机器人在房间内,安装的提及开关开启,且该指令已在房间选用 |
slash | 房间消息以 /命令 参数 开头 | bot:events:read、bot:room:slash;平台逐条核准该指令,房间管理者也逐条启用 |
平台批准斜杠指令后,房间仍须自行启用。普通房间聊天、句中提及、未知或无法唯一定位机器人的命令不会产生事件;机器人发送的消息也不会触发另一轮机器人事件。
指令登记时会去除首尾空白并转为小写,名称为 1–32 个 ASCII 小写字母、数字、下划线、常用中文或连字符,首字符不能是连字符;触发时精确匹配登记名。参数按空白拆分,不支持 shell 引号语法。超过 10 项时不识别为指令,也不生成事件;对于已识别的指令,参数数量不符合该指令配置时,人工用户的原消息仍会保存,发送响应包含 command_error,机器人不会收到该事件。
读取事件
curl 'http://127.0.0.1:4520/v1/bots/me/events?after=0&limit=50' \
-H 'Authorization: Bearer <bot-pat>'
after 是十进制字符串,首次读取使用 "0",最大为 "9223372036854775807"。limit 默认为 50,可设为 1–50。必须使用机器人的 PAT;所有者自己的 PAT、OAuth access token 和 Cookie 均不能代替它。
下面把三类事件放在同一个响应中,展示各字段的差异。ID、时间与内容均为示例。
{
"events": [
{
"event_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"seq": "1",
"message_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
"room_id": null,
"conversation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
"trigger_kind": "dm",
"command_id": null,
"command_revision": null,
"args": [],
"content": "你好,可以查一下服务器状态吗?",
"author_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
"created_at": "2026-11-08T00:00:00.000Z"
},
{
"event_id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
"seq": "2",
"message_id": "01ARZ3NDEKTSV4RRFFQ69G5FB0",
"room_id": "01ARZ3NDEKTSV4RRFFQ69G5FB1",
"conversation_id": null,
"trigger_kind": "mention",
"command_id": "01ARZ3NDEKTSV4RRFFQ69G5FB2",
"command_revision": 1,
"args": ["play.example.com"],
"content": "@status-bot 查服 play.example.com",
"author_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
"created_at": "2026-11-08T00:00:01.000Z"
},
{
"event_id": "01ARZ3NDEKTSV4RRFFQ69G5FB3",
"seq": "3",
"message_id": "01ARZ3NDEKTSV4RRFFQ69G5FB4",
"room_id": "01ARZ3NDEKTSV4RRFFQ69G5FB1",
"conversation_id": null,
"trigger_kind": "slash",
"command_id": "01ARZ3NDEKTSV4RRFFQ69G5FB2",
"command_revision": 1,
"args": ["play.example.com"],
"content": "/查服 play.example.com",
"author_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
"created_at": "2026-11-08T00:00:02.000Z"
}
],
"next_after": "3"
}
| 字段 | 含义 |
|---|---|
event_id | 事件 ID,回复时原样传入 |
seq | 当前机器人的事件序号,十进制字符串 |
message_id | 触发事件的人工消息 ID |
room_id | 房间 ID;私信为 null |
conversation_id | 私信会话 ID;房间事件为 null |
trigger_kind | dm、mention 或 slash |
command_id | 触发的房间指令 ID;私信为 null |
command_revision | 触发时的指令修订号;私信为 null |
args | 已拆分的指令参数;私信为空数组 |
content | 人工用户发送的完整消息文本 |
author_id | 发送消息的人工用户 ID |
created_at | 事件创建时间,ISO 时间字符串 |
正确保存游标
事件按 seq 升序返回,但只包含当前仍有权限查看的消息。消息删除、权限变化或过期清理都可能造成序号间隔。
处理完一页后,保存响应中的 next_after,下次原样作为 after 传入。空页也可能推进 next_after;不要自行取最大序号、加一或猜测连续性。不要把 seq 或游标转为 JavaScript Number,大整数会丢失精度;也不要把本地未收到的较大数字当成游标。
同一机器人、相同 scope 集合、同一消费任务的多个实例应协调使用同一份持久化游标,避免相互覆盖进度。不同 scope 或独立业务消费者分别保存游标,防止一方推进后跳过另一方尚未处理的事件。首次启动、建立 WebSocket、重连以及正常运行期间,都应主动调用 HTTP 补取。
回复与重复请求
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":"01ARZ3NDEKTSV4RRFFQ69G5FAV","action_key":"status-v1","content":"服务器在线。"}'
成功返回 {"message_id":"…","duplicate":false}。回复发送到原事件对应的私信会话或房间,无需再指定目标。action_key 为 1–64 个 ASCII 英文字母、数字、下划线、连字符、冒号或点;相同业务动作应稳定使用同一个键。content 去除首尾空白后不能为空,最长 10000 字符。
同一机器人、event_id 和 action_key 的重复请求返回首次发送的 message_id,并设置 duplicate: true;改变 content 不会覆盖首次回复。每个事件最多接受 5 个新的回复键,重试已有键不占新额度。不要在每次重试时随机生成键。
回复前会重新检查当前资格,包括 PAT、授权、源消息、房间安装与成员、指令修订和开关;私信还检查双方拉黑及对方消息隐私设置。私信回复需要 bot:dm:reply,房间回复需要 bot:room:reply,并保留触发该事件所需的读取权限。读取到事件并不保证稍后一定还能回复,幂等重试也不能绕过资格复核。
TypeScript 消费示例
将下面代码保存为 bot-consumer.ts。它处理一页事件,每个事件发送一次确认;你可以将确认文本替换为自己的业务结果。ack-v1 在每次重试时保持一致。
type BotEvent = { event_id: string; seq: string }
type EventPage = { events: BotEvent[]; next_after: string }
type ConsumerOptions = {
baseUrl: string
token: string
loadCursor: () => Promise<string>
saveCursor: (cursor: string) => Promise<void>
fetcher?: typeof fetch
}
export async function consumePage({
baseUrl, token, loadCursor, saveCursor, fetcher = fetch,
}: ConsumerOptions): Promise<number> {
const headers = { Authorization: `Bearer ${token}` }
const url = new URL('/v1/bots/me/events', baseUrl)
url.search = new URLSearchParams({ after: await loadCursor(), limit: '50' }).toString()
const response = await fetcher(url, { headers, credentials: 'omit', redirect: 'error' })
if (!response.ok) throw new Error(`读取失败:${response.status} ${await response.text()}`)
const page = await response.json() as EventPage
for (const event of page.events) {
const reply = await fetcher(new URL('/v1/bots/me/replies', baseUrl), {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
credentials: 'omit',
redirect: 'error',
body: JSON.stringify({
event_id: event.event_id,
action_key: 'ack-v1',
content: '已收到你的消息。',
}),
})
if (!reply.ok) throw new Error(`回复失败:${reply.status} ${await reply.text()}`)
await reply.json() // 消费响应体;响应中断时保留游标,重试仍使用原回复键。
}
// 所有回复成功后才提交整页进度;空页也保存服务端返回的游标。
await saveCursor(page.next_after)
return page.events.length
}
例如在 Node.js 中用本地文件保存游标。将以下内容保存为同目录的 run-bot.ts,配置环境变量 BOT_TOKEN、BOT_API_ORIGIN,使用支持 TypeScript 的 Node.js 运行 node run-bot.ts:
import { readFile, writeFile, rename } from 'node:fs/promises'
import { setTimeout as delay } from 'node:timers/promises'
import { consumePage } from './bot-consumer.ts'
const token = process.env.BOT_TOKEN
const baseUrl = process.env.BOT_API_ORIGIN
if (!token || !baseUrl) throw new Error('请配置 BOT_TOKEN 与 BOT_API_ORIGIN')
const cursorFile = new URL('./bot-cursor.txt', import.meta.url)
const temporaryFile = new URL('./bot-cursor.tmp', import.meta.url)
async function loadCursor(): Promise<string> {
try { return (await readFile(cursorFile, 'utf8')).trim() }
catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return '0'
throw error
}
}
async function saveCursor(cursor: string): Promise<void> {
await writeFile(temporaryFile, cursor, 'utf8')
await rename(temporaryFile, cursorFile)
}
while (true) {
const count = await consumePage({ baseUrl, token, loadCursor, saveCursor })
if (count === 0) await delay(5000)
}
此示例使用单进程,每页完成后替换游标文件。发生读取、回复或保存错误时会停止,排查后可使用原游标重启;上一页已成功的确认会通过相同回复键去重。若还要写数据库、调用第三方服务等,应为这些副作用另外保存处理状态和幂等键,事件回复接口不会替你的业务事务去重。
WebSocket 变化提示
连接 wss://<API 域名>/v1/bots/me/events/stream,握手时使用 Authorization: Bearer <bot-pat>。接口拒绝 Cookie、URL 查询参数、请求正文和 Sec-WebSocket-Protocol;令牌不要放进 URL。网页原生 WebSocket 不能设置这个请求头,应使用支持自定义握手头的服务端客户端。
唯一的应用层通知如下:
{"event":"bot_events_changed"}
收到通知后调用读取接口。通知没有事件序号、正文或确认机制,可以合并、重复或丢失;新连接不会为已有待处理事件发送初始提示,所以建连后应立即补取,并保留周期性 HTTP 轮询。
客户端不发送订阅或确认消息,任何客户端应用数据帧(包括空帧)都会使连接结束;标准 ping/pong 控制帧由客户端库正常处理。每条连接最长 30 分钟,每个 token 最多 2 条、每个网关实例最多 64 条连接。断流后适当退避重连,继续从持久化 next_after 获取正文;不要因为断流把游标重置为零。
错误与事件保留
| HTTP 状态 | 处理方式 |
|---|---|
400 | 检查参数格式、游标上限和正文;修正后再请求 |
401 | 检查机器人 PAT 是否失效或过期,更新凭据 |
403 | 检查 scope、当前授权、账号状态及会话或房间资格;不要靠重复请求绕过 |
404 | 源事件或消息不存在,可能已删除或被清理;记录处置后再决定是否跳过 |
429 | 读取响应中的限流信息并退避;若已达到每事件五个回复上限,不再创建新回复键 |
5xx 或网络中断 | 保留游标,退避后重试同一动作;发送结果未知时也沿用原回复键 |
事件与关联回复幂等记录按事件创建时间保留 90 天,后台分批清理;不以最后回复时间延长。清理不删除聊天消息,也不重置事件序号,但旧事件将不能继续回复。长期离线可能丢失未处理事件,不应依赖从零重放完整聊天历史。
机器人事件与资源 Webhook是不同通道:前者用于机器人消息和指令,后者投递资源发布变化;Webhook 的网站 Cookie 管理接口不接受机器人 PAT。