跳转到内容

实时事件

除了轮询,bot 可以连上实时通道接收事件。通道与 App 用的是同一个(push 服务),事件受众由服务端按会话成员/可见性计算——bot 是成员就能收到。

POST /api/v1/ws (带 Authorization: Bearer ofb_…)
→ 200 {"ticket":"<64 位十六进制>","expires_in":30}
GET /api/v1/ws?ticket=<ticket> (WebSocket 升级;URL 用 ws:// 或 wss://)
规则 说明
票据 一次性,用掉即失效
有效期 30 秒,只够“取票 → 立刻连接”这段间隔
过期 / 用过 / 不存在 一律拒绝

连上后首先收到一句问候:

{"type":"connected"}

之后每条消息都是同一个信封:

{
"type": "chat.message.created",
"recipients": [7, 4242],
"data": {
"id": 9001,
"conversation_id": 33,
"sender_id": 7,
"kind": "text",
"content": "你好",
"created_at": "2026-10-10T15:22:41Z"
}
}

data 就是对应的资源对象(消息事件给消息对象,帖子事件给帖子对象);上面只列了几个字段,完整字段见消息模型。

type data 受众
chat.message.created 消息对象 会话内 active 成员
chat.message.updated 消息对象 同上
chat.message.deleted 消息对象 同上
chat.typing {conversation_id, user_id} 会话成员
chat.conversation.updated {conversation_id} 会话成员
chat.consent.requested {user_id, encrypted, …} 被请求方
chat.e2ee.keys.updated 密钥信封元数据 会话成员
post.created 帖子对象 见下方「可见性」
post.deleted 帖子对象 同上
post.reply.created / .updated / .deleted 评论对象 帖子作者等相关方
call.invited / call.ended 等 通话载荷 见通话

post.created 的受众按可见性计算:private 只发作者,friends 发互关好友 + 作者,public / login 是广播给所有已连接客户端(recipients 为空数组即广播)。

  • 服务端每 54 秒发一个 ping,读超时 60 秒——bot 必须及时回 pong(多数 WebSocket 库自动处理),否则连接被断开;
  • 每个连接的发送缓冲是 256 条,写不进去(消费太慢)会被直接断开,不做堆积。请务必及时处理事件,代价高的操作丢进自己的队列;
  • 事件是 PostgreSQL NOTIFY 转发的尽力而为投递,不是持久队列:服务重启、连接掉线期间的事件不会补发。
import asyncio, json, websockets
async def listen(bot, ws_base):
while True:
try:
_, res = bot.request("POST", "/api/v1/ws") # 取票
async with websockets.connect(
f"{ws_base}/api/v1/ws?ticket={res['ticket']}") as ws:
async for raw in ws:
evt = json.loads(raw)
if evt.get("type") != "chat.message.created":
continue
data = evt.get("data") or {}
if data.get("sender_id") == BOT_ID or data.get("sender_is_bot"):
continue
await handle(data)
except Exception:
await asyncio.sleep(5) # 断线重连;事件不补发,重连后按轮询对账

注意三件事:取票后再连、跳过自己与其他 bot、断线后重连并补对账。