Webhook 与轮询

反应型机器人的默认 inbox 是 签名 HTTPS Webhook，再用 GET /api/v1/bots/me/events 把漏掉的事件补回来。机器人不会接入 /chat WebSocket。

当前会推送的叫醒只有一种：群成员用 picker 发出结构化斜杠命令（消息带 meta.botCommand）时，平台写入一条 interaction.created，并在主人已登记 active 回调时签名 POST 过去。@ 提及、被回复的 webhook 面仍在收紧中，还没有对自助机器人开放。

这和机器人资料上的「来源类型 webhook」不是一回事。来源标记仍需官方开通；这里说的是主人给自己的机器人登记 HTTPS 回调，普通账号即可使用。

什么时候用哪条路径

群管理员安装机器人时看不到回调 URL，也没有名为 Webhook 的勾选。地址只对机器人主人可见。Mobile 目前没有主人侧的回调设置界面，请用 Web「设置 → 自动化机器人」或 CLI。

登记回调

先让你的服务监听一个公开 HTTPS地址，能接收 JSON POST。然后用账号密钥（不是机器人 runtime key）登记：

# Web：设置 → 自动化机器人 → 对应机器人 → 回调地址 → 验证并保存

2s1 bot endpoint create <botUserId> --url https://example.com/bot/events --yes
2s1 bot endpoint show <botUserId>
2s1 bot endpoint pause <botUserId> --yes   # 暂停出站；事件仍可 pull

登记时平台会先发一条验证请求。对端必须在超时内返回 2xx，响应 JSON 里回显同一个 challenge：

{
  "type": "endpoint.verify",
  "challenge": "<平台生成的字符串>",
  "endpointId": "<endpointId>",
  "botUserId": "<botUserId>"
}

你的响应至少包含 { "challenge": "<原样回显>" }。验证通过后状态变为 active，斜杠命令才会出站。URL 必须是 HTTPS、不能带用户名密码；内网和回环地址会被拒绝。

收到事件之后

叫醒 POST 的 body 是事件信封本身，当前类型为 interaction.created，data.interactionType 为 "command"。请按原始字节验签，不要先 pretty-print 再算签名。

请求头：

签名内容是 timestamp.endpointId.body（三个字段用英文句点拼接，body 为原始 JSON 字符串）。公钥在 2s1 bot endpoint show 或 Web 回调对话框里，算法为 Ed25519。SDK 可直接调用 verifyBotWebhookSignature；默认允许约 5 分钟时钟偏差。

处理成功请返回 2xx。投递失败后请用事件 feed 补拉，不要假设平台会无限重试到你的进程醒来。

用事件 feed 补拉

新轮换的 runtime key 自动带 events.read。这不是群安装授权，也不是 chat.read。

curl "https://2some.ren/api/v1/bots/me/events?limit=100" \
  -H "x-api-key: $TWOSOMEONE_BOT_API_KEY" \
  -H "x-2someone-bot-runtime: 1"

TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test events --limit 20

cursor 是不透明字符串，只把上次响应里的 nextCursor 原样传回去。wait 非 0 会返回 400，当前不做 long poll。暂停回调后，这条 pull 路径仍然可用。

完整字段、curl 和 429 处理见接口参考。

轮询限额

GET .../messages 和 GET .../messages/:messageId/thread 轮询仍然保留。可见范围继续由 chat.read 和这次安装的隐私模式决定；充值 VIP 不会把 read_all 开放给普通自助机器人。

这两条拉消息接口有单独限额，按机器人主人当前充值 VIP 即时生效（升级后不必轮换密钥）。同一把 runtime key 下，所有会话的分页请求共用一个桶，每一页都计数：

运行密钥本身仍是整把 key 的总限额：自助轮换默认 100 次/分钟（Webhook 档，发消息、事件 feed、webhook 相关调用共用）。管理员账号轮换时可盖更高的整把 key 限额；自定义 rateLimitMax 仍需管理员。已经发出的旧密钥如果曾盖过 5000，会保持到下次轮换。

触发拉消息限额时返回 429，code: rate_limited，并带 Retry-After / X-RateLimit-*。反应型机器人应默认走 webhook / 事件 feed；只有需要监控会话里更多内容时，才按 VIP 档控制 chat.read 频率。VIP 权益说明见用户等级与充值 VIP。