首页 产品 为什么选 OCTO 解决方案 文档 关于
文档中心 / API 与集成 / Bot API 快速入门
← 返回文档中心

Bot API 快速入门

OCTO 文档中心 · API 与集成
  • source-repos/octo-server/modules/bot_api/（路由/鉴权/文件/群组源码）
  • 00-inbox/product-bot-answers/2026-09-20-P0-API鉴权-Q1回答.md（API体系全貌，Q1）
  • 00-inbox/product-bot-answers/2026-09-20-P0-API鉴权-Q2回答.md（双token鉴权模型，Q2）
  • 00-inbox/product-bot-answers/2026-09-20-P0-文件API-Q4回答.md（文件上传下载端点，Q4）
  • 00-inbox/product-bot-answers/2026-09-21-P1-Docs-Q6回答.md（文档评论@Bot链路，Q6）
  • 00-inbox/product-bot-answers/2026-09-21-P1-Marketplace-Q7回答.md（Bot作为Marketplace creator，Q7）
  • 00-inbox/product-bot-answers/2026-09-22-P1-r2-Q9-BotAPI与消息类型全景回答.md（Q9 源码确认级：token/事件/限流/卡片/互调）
  • octo-web packages/dmworkbase/src/Service/Const.ts（MessageContentType 枚举）
  • 01-product/模块说明/Drive网盘模块.md v0.3（Bot对网盘零面，源码确认）
  • 01-product/模块说明/语音Speech模块.md v0.3（语音纠错API）
  • 01-product/模块说明/全文搜索Search模块.md v0.3（Bot OBO搜索）
  • 06-api-integration/Bot-API概览.md v0.4（端点清单基线）

Bot API 快速入门 v1.0

面向第一次接入 OCTO Bot 的开发者。本文档基于 octo-server v1.18.0 开源源码 + 产品管家 Q1/Q2/Q4/Q6/Q7/Q9 回答（截至2026-09-22）。v1.0 已基于 Q9 源码确认升级：token格式、HTTP长轮询事件、消息类型枚举、卡片能力、限流、管理清单、互调防循环均已源码级确认。

🔴🔴🔴 三个售前易错点（必须先看！）

下列三点是售前/集成场景最容易说错的，文档中所有相关章节已据此纠偏。

🔴 ① Bot 收事件 = HTTP 长轮询，不是 WebSocket / Webhook

  • 端点：POST /v1/bot/events（带 wait 字段，单次 hold 上限 30s；底层 Redis sorted-set + doorbell BLPOP）
  • 不存在 WebSocket 推送，Bot 事件通道上不存在可配置的 Webhook 回调（注：平台级出站 Webhook /v1/webhook、/v2/webhook 是另一 API 面，用于外部系统接收 IM 事件回调，非 Bot 收事件通道，两者不矛盾）
  • 售前/POC 方案中禁止出现"Bot通过WebSocket/Webhook接收事件"的表述

🔴 ② Bot Token 是 `bf_` 前缀，不是 `bt_`

  • 三类 token 前缀：User Bot bf_ / App Bot app_ / User API Key uk_
  • bf_ = 16 字节随机数 hex（bf_ + 32 hex 字符），crypto/rand 生成
  • 任何文档/示例/截图中出现 bt_、sk_ 前缀一律错误
  • Token无过期时间【✅源码确认 A-6补证 2026-09-22：robot表bot_token字段无expires列，authUserBot仅查询bot_token=? and status=1，token永不自动过期，仅手动重置或Bot删除/禁用时失效】；IM层凭证（imToken）有有效期，过期后重新register刷新

🔴 ③ Bot 目前收不到 reaction / 群成员变动 / 加入退出 / 被移除 / 网盘分享事件

  • 源码未找到向 Bot 事件队列投递这些事件的写入点（MessageResp.Reactions 字段被注释掉）
  • 售前禁止承诺"Bot 可监听群成员加入/退出/表情回应"

1. Bot 是什么

  • 可添加到群聊，作为群成员收发消息
  • 通过 HTTP 长轮询接收消息事件，包括普通消息(DM/@)、卡片回调(card_action)、文档评论@Bot、bot_setting 卡片事件
  • 回复消息，支持文本、图片、文件、语音、位置、名片、gif、小视频、合并转发、贴图、富文本、互动卡片(type=17)、文档转发卡片等多种消息类型
  • 以自身身份操作，默认权限等同于普通群成员
  • 可上架 Marketplace，作为 skill/connector 的 creator

1.1 Bot 能做什么（Q9 已确认能力清单）

能力 状态 来源
加入群聊，通过 HTTP 长轮询接收 DM/@ 事件 ✅ 源码确认 Q9 BA-02 + bot_api/events.go
被@时触发事件（群聊@ + 文档评论@） ✅ 源码确认 Q6 + Q9（事件源①③）
卡片按钮/表单回调（card_action, v2 profile） ✅ 源码确认 Q9 BA-01（事件源②）
发送消息（全10+消息类型，含互动卡片type=17） ✅ 源码确认 Q9 BA-01（Const.ts枚举）
动态改卡（POST /v1/bot/message/edit + card_seq CAS） ✅ 源码确认 Q9 BA-01
上传/下载聊天附件（5个文件API端点） ✅ 源码确认 Q4 + Q9
建群 / 改群名 / 改公告 ✅ 源码确认 Q9 BA-04
加/移除群成员 ✅ 源码确认 Q9 BA-04
Thread 全套（建/删/加入/退出/归档/改MD） ✅ 源码确认 Q9 BA-04
群 MD 读写 ✅ 源码确认 Q9 BA-04
Typing 指示器 / 已读回执 ✅ 源码确认 Q9 BA-04
消息编辑 ✅ 源码确认 Q9 BA-04
@群成员 / @所有人 ✅ 源码确认 Q9 BA-04
语音转写 ✅ 源码确认 Q9 BA-04
群入站 Webhook 管理 ✅ 源码确认 Q9 BA-04
发私信（Person 频道） ✅ 源码确认 Q9 BA-04（App Bot 仅 DM 过滤反向佐证）
管理语音纠错词典（人名/术语） ✅ 源码确认 语音模块 v0.3
以 Bot 主人身份搜索消息（OBO） ✅ 源码确认 搜索模块 v0.3
接收文档评论@Bot事件并写回回复 ✅ 源码确认 Q6 Docs 模块
作为 Marketplace creator 上架插件 ✅ 源码确认 Q7 Marketplace 模块

1.2 🔴 Bot 不能做什么（已确认边界——售前/开发必读）

禁区 证据 说明
不能操作 Drive 网盘文件 🔴 P0 源码确认：/v1/bot/drive/ 全仓 0 命中 Bot 没有任何 Drive API；网盘操作零面
不能改群头像 🔴 Q9 BA-04 源码确认 改群 req 仅 Name/Notice 字段
不能禁言 mute 🔴 Q9 BA-04 源码确认 无 mute 端点
不能设管理员 🔴 Q9 BA-04 源码确认 无 set-admin 端点
收不到 reaction/群成员变动/加入退出/被移除/网盘分享事件 🔴 Q9 BA-02 源码确认 MessageResp.Reactions 被注释，无投递点
不支持卡片 Action.Execute / auto-refresh 🔴 Q9 BA-01 源码确认 卡片白名单不含这两项
不能跨群操作非成员群 Q2 权限模型 必须是群成员，否则 ErrBotAPINotGroupMember
不是群超管 Q2 Bot 加群后是普通群成员
不能获得超越创建者的权限 Q7 Bot 作为 Marketplace creator 时，owner 同 Bot owner，无权限增益
文档创建/编辑非直接 Bot API Q9 BA-04 需经 octo-cli 用 Bot token 调 docs API
无 Bot 间直接 API 互调 Q9 BA-05 Bot 间交互靠群消息 fan-out，无 bot-to-bot RPC

⚠️ 售前红线：不要向客户承诺"Bot 可以读写网盘""Bot 可以监听群成员变动""Bot 通过 WebSocket 收事件""Bot 可以直接创建/编辑文档（不经 octo-cli）"。这些都是硬禁止口径。详见 [售前红线卡](../08-presales-delivery/售前红线卡-v1.0.md)。

1.3 BotFather ≠ Marketplace（售前强口径）

组件 职责
BotFather Bot 的创建/注册/bot_token 发放/基础配置/runtime onboarding；/revoke 可重置 token
Marketplace 插件（expert/expert_team/skill/connector）的上架/分发/版本管理/审核

2. 创建 Bot

2.1 创建入口：BotFather

  • bot_token：长期身份凭据，用于所有 /v1/bot/* API 鉴权
  • Bot 的基本配置（名称、头像、描述等）

📝 创建入口/自助流程/审批流程：待后续 Q 补充（BA-01，非 P0，不阻塞 v1.0 发布）。

Token 格式（✅ Q9 BA-03 已源码确认）
Token 类型 前缀 格式 用途
User Bot Token bf_ bf_ + 32 hex 字符（16 字节 crypto/rand） 标准 Bot 身份凭据，调 /v1/bot/*
App Bot Token app_ app_ + … App/集成类 Bot，受 scope 约束（fail-closed）
User API Key uk_ uk_ + … 用户个人 API Key（非 Bot） 
Authorization: Bearer bf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🔴 任何文档/示例中出现 `bt_`、`sk_` 前缀一律错误。

2.2 Bot 类型

类型 token 前缀 存储表 特点
User Bot bf_ robot 表 标准 Bot，以自身身份操作，可收 DM/@/card_action/文档@/bot_setting 五类事件
App Bot app_ app_bot 表 有 scope 约束（如 space 级别），fail-closed；事件过滤仅保留 DM（Person 频道）——filterAppBotEvents 过滤非 Person 频道事件

📝 App Bot 的 scope 完整枚举待后续补充（BA-03，非 P0）。

2.3 Token 重置（✅ Q9 BA-03 已确认）

  • 通过 BotFather /revoke 命令重置
  • 需要输入 "Yes, revoke it" 作为二次确认（防误操作）
  • 旧 token 立即失效（tombstone 机制）
  • 重置后正在使用旧 token 的长轮询/业务调用会立即 401，需要客户端用新 token 重连

⚠️ 泄露风险（Q9 确认）：bot_token = Bot 全部权限凭证。泄露后攻击者可冒充 Bot 发消息、读事件、管理已加入的群。OBO（on-behalf-of）代发受额外 grant + scope 校验，不能仅凭 bot_token 冒充用户。

3. 安装 Bot 到群

📝 本节自助安装流程细节（安装入口/搜索→添加→确认/管理员审批/默认权限/安装事件回调）为非 P0 项，待后续补充（BA-05），不阻塞 v1.0 发布。

  • Bot 加群后是普通群成员，非超管（来源：Q2）
  • Bot 只能操作自己已加入的群（来源：Q2）
  • GET /v1/bot/groups 返回自己加入的群列表（来源：源码）
  • 群入站 Webhook 可由 Bot 管理（Q9 BA-04）

4. 鉴权方式

4.1 鉴权概览

GET /v1/bot/groups HTTP/1.1
Host: your-octo-server.example.com
Authorization: Bearer bf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Token 类型：opaque 字符串（非 JWT）
  • Token 前缀识别身份类型：bf_（User Bot）/ app_（App Bot）/ uk_（User API Key）
  • bf_ token = bf_ + 32 hex 字符（16 字节 crypto/rand 生成）
  • 吊销即时生效（tombstone 缓存机制）

⚠️ bot_token 是敏感凭据，绝不要在前端代码、公开仓库、客户端二进制中暴露。

4.2 限流策略（✅ Q9 BA-03 已源码确认）

桶 用途 IP 底线（源码硬编码） 说明
business 业务操作（sendMessage、群组管理、编辑等） 待运行时 config 确认 ❌ 主配额，按 bot 身份分桶；具体 RPS/日配额由 system_setting 动态配置，源码无硬编码默认值
heartbeat 保活（POST /v1/bot/heartbeat） 500 rps / IP 独立配额，自愈不连坐；Redis TTL 60s
register 换 token（POST /v1/bot/register） 100 rps / IP key=bot token 指纹，鉴权前限流，防暴力枚举

⚠️ business 桶具体 RPS/日配额默认值需在部署时从 `system_setting` 查询（BA-07，待确认）。

4.3 连接生命周期（register / heartbeat）

Bot 启动
  ↓
POST /v1/bot/register（Authorization: Bearer bf_xxx）→ 获取短期 IM 连接凭证
  ↓
（如需 WuKongIM 长连接，用 IM token 建立连接——Bot 收业务事件不需要这步，见 §5.2）
  ↓
定期 POST /v1/bot/heartbeat 保活（Redis TTL 60s）
  ↓
凭证过期 → 重新 register
  • /v1/bot/register 和 /v1/bot/heartbeat 是连接管理端点，2026-08-05 事故后从全局桶中分离出独立限流桶
  • 注意：Bot 接收业务消息事件（§5.2）使用的是 HTTP 长轮询 POST /v1/bot/events（直接走 business 桶），不是 WuKongIM 长连接；register/heartbeat 主要用于 IM 底层连接保活（Bot 框架按需调用）

📝 register/heartbeat 完整请求/响应 payload 及 WuKongIM 连接参数（host/port/protocol）待后续补充（BA-06，非 P0）。

5. 发送消息与接收事件（✅ Q9 核心确认）

5.1 发送消息：POST /v1/bot/sendMessage

POST /v1/bot/sendMessage
Authorization: Bearer bf_xxx
Content-Type: application/json
Hello World 示例（发一条文本消息）
curl -X POST "https://your-octo-server.example.com/v1/bot/sendMessage" \
  -H "Authorization: Bearer bf_your_bot_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": 2,
    "channel_id": "目标群ID",
    "type": 1,
    "content": "Hello, OCTO! 我是你的第一个Bot 🤖"
  }'
消息类型完整枚举（✅ Q9 BA-01 源码确认，Const.ts:52）
type 内容 备注
1 文本 最常用
2 图片
3 gif
4 语音
5 小视频
6 位置
7 名片
8 文件 配合文件上传 API
11 合并转发
12 lottie 贴图
13 emoji 贴图
14 富文本图文混排
17 互动卡片 Adaptive Card 见 §5.1.1
18 文档转发卡片
20 截屏
1002+ 群系统消息 系统类，Bot 一般不主动发

📝 各类型 content 字段的详细 schema 待《消息类型与发送-v1.0》专题文档展开。

5.1.1 互动卡片 type=17（✅ Q9 BA-01 源码确认）
  • 基于 Adaptive Cards 协议，两档 profile：
  • octo/v1：纯展示
  • octo/v2：支持交互（输入+Submit回调）
  • 展示元素白名单：TextBlock / RichTextBlock / Image / ImageSet / Container / ColumnSet / FactSet / Table / ActionSet
  • 输入元素（v2）：Input.Text / Input.Toggle / Input.ChoiceSet / Input.Number / Input.Date / Input.Time
  • 动作：本地 OpenUrl / ToggleVisibility / CopyToClipboard；Action.Submit（回调服务端，v2 专属）
  • 🔴 不支持：Action.Execute / auto-refresh
  • 限制：payload ≤ 512 KiB / body ≤ 2 MiB / 节点 ≤ 200 / 深度 ≤ 16
  • ✅ 动态改卡：POST /v1/bot/message/edit + octo_message_card_revision 表 + card_seq CAS 并发控制（乐观锁，基于序列号防止并发改卡冲突）

5.2 接收事件：HTTP 长轮询 POST /v1/bot/events（✅ Q9 BA-02 源码确认）

🔴 纠偏：v0.1 框架曾写"WebSocket/WuKongIM 长连接 或 Webhook 回调，待确认"。Q9 源码确认：Bot 收事件 = HTTP 长轮询，不是 WebSocket，不是 Webhook。

端点
POST /v1/bot/events
Authorization: Bearer bf_xxx
Content-Type: application/json

{
  "wait": 30
}
  • 方法：POST
  • 路径：/v1/bot/events
  • wait 字段：单次 hold 上限 30 秒
  • 底层：Redis sorted-set 队列 + doorbell BLPOP 唤醒
  • Bot 客户端典型模式：循环调用——拿到事件立即处理，处理完（或 hold 超时无事件）立刻发起下一次 POST
5 个事件写入源（Q9 源码确认）
序号 事件源 说明
① 普通消息 (DM/@) 私聊消息、群内 @Bot 消息
② card_action 卡片按钮/表单回调（v2 Action.Submit）
③ 文档评论 @Bot docs-backend 经内部端点 /v1/internal/bot-mentions 投递
④ bot_setting 卡片事件 BotFather/设置类卡片交互
— ❌ reaction / 群成员变动 / 加入退出 / 被移除 / 网盘分享 无投递点，Bot 收不到
App Bot 事件过滤
  • App Bot（app_ token）经 filterAppBotEvents 仅保留 Person 频道（DM）事件，群消息被过滤掉
Event payload 结构
{
  "message_id": "...",
  "message_seq": 12345,
  "from_uid": "uid...",
  "timestamp": 1726972800,
  "channel_id": "...",
  "channel_type": 2,
  "payload": { /* 消息体，按 type 解析；回复上下文在 WuKongIM reply 字段内 */ }
}
  • typed 事件（如 card_action）带 event_type + event_data
  • ⚠️ 无独立 in_reply_to 顶层字段，回复上下文在 payload 内（WuKongIM reply 结构），Bot 需自行解析

6. 已确认 API 端点清单

6.1 消息与事件

方法 端点 用途 来源
POST /v1/bot/sendMessage 发送消息（全类型，含卡片 type=17） Q9 BA-01
POST /v1/bot/message/edit 编辑消息 / 动态改卡（card_seq CAS） Q9 BA-01
POST /v1/bot/events HTTP 长轮询收事件 Q9 BA-02

6.2 文件 API（5个端点，Q4 + Q9 确认）

方法 端点 用途 来源
POST /v1/bot/file/upload 上传聊天附件（multipart） Q4 + bot_api/file.go
GET /v1/bot/file/download/*path 下载文件，返回 302 重定向到预签名 URL Q4 + bot_api/file.go
GET /v1/botfile/*path 代理访问文件（OCTO 服务端中转） Q4 + bot_api/file.go
POST /v1/bot/upload/credentials 获取 STS 临时凭证（客户端直传S3） Q4 + bot_api/file.go
POST /v1/bot/upload/presigned 获取预签名 PUT URL（直传） Q4 + bot_api/file.go
  • 🔴 上传 key 硬编码前缀 chat/，只能上传到聊天附件命名空间
  • 🔴 Bot 不能上传文件到 Drive 网盘（与§1.2 零面一致）
  • 下载走 302 预签名 URL，Bot 无需持有存储凭证

6.3 群组与 Thread 管理（Q9 BA-04 确认存在；完整端点路径见《Bot-API概览》）

能力 端点状态 来源
获取已加入群列表 GET /v1/bot/groups ✅ 已确认 Q2 + 源码
建群 ✅ 存在 Q9 BA-04
改群名 / 改公告 ✅ 存在（仅 Name/Notice 两字段；不能改头像） Q9 BA-04
加成员 / 移除成员 ✅ 存在 Q9 BA-04
Thread 全套（建/删/加入/退出/归档/改MD） ✅ 存在 Q9 BA-04
群 MD 读写 ✅ 存在 Q9 BA-04
群入站 Webhook 管理 ✅ 存在 Q9 BA-04
❌ 禁言 mute 不存在 Q9 BA-04
❌ 设管理员 不存在 Q9 BA-04
❌ 改群头像 不存在 Q9 BA-04

6.4 Typing / 已读 / @ / 语音 / 私信（Q9 BA-04 确认存在）

能力 来源
Typing 指示器 Q9 BA-04
已读回执 Q9 BA-04
@群成员 / @所有人 Q9 BA-04
语音转写 Q9 BA-04
发私信（Person 频道） Q9 BA-04

6.5 语音纠错 API

方法 端点 用途 来源
待补全 /v1/bot/voice/context 管理语音识别专有名词/术语词典，提升转写准确率 语音模块 v0.3

📝 语音纠错 API 完整方法（GET/POST/PUT/DELETE）、payload 格式待补充（BA-11，非 P0）。

6.6 搜索 API（OBO）

方法 端点 用途 来源
POST /v1/botfather/messages/search 以 Bot 主人身份搜索消息（OBO 模式，受 grant+scope 校验） 搜索模块 v0.3

📝 搜索 API payload/范围/分页/返回格式待补充（BA-12，非 P0）。

6.7 连接管理

方法 端点 用途 来源
POST /v1/bot/register 用 bot_token 换取短期 IM 连接凭证；register 桶 IP 底线 100 rps Q2 + Q9 + auth.go
POST /v1/bot/heartbeat 保活（Redis TTL 60s）；heartbeat 桶 IP 底线 500 rps Q2 + Q9 + auth.go

6.8 内部端点（非 Bot 直接调用）

方法 端点 用途 来源
POST /v1/internal/bot-mentions docs-backend 调用，转发文档评论@Bot事件 → Bot 在 /v1/bot/events 收到 Q6 Docs 模块

⚠️ 此端点为内部服务间调用，Bot 开发者不直接对接。

6.9 文档评论@Bot 链路（✅ Q6 已确认完整流程）

用户在文档中 @Bot
  ↓
docs-backend 捕获评论
  ↓
docs-backend → POST /v1/internal/bot-mentions（内部端点）
  ↓
Bot 长轮询 /v1/bot/events 收到 doc_comment_mention 事件（事件源③）
  ↓
Bot 处理并生成回复
  ↓
Bot 调用 docs comments API（带 --parentId，经 octo-cli 用 Bot token 调 docs API）→ 回复写回文档评论区

⚠️ 文档创建/编辑不是直接 Bot API 路径，需经 `octo-cli` 使用 Bot token 调用 docs API（Q9 BA-04）。

7. Bot 间互调与级联（✅ Q9 BA-05 源码确认）

7.1 无 Bot 直接调另一 Bot 的 API

  • 不存在 Bot-to-Bot RPC 机制（无 call_bot / bot_invoke 端点）
  • Bot 间交互靠群消息 fan-out：Bot A 在群发消息 → 群内其他 Bot（包括 Bot B）通过长轮询各自收到该消息事件 → 各自处理

7.2 OBO（on-behalf-of，代发）三重防循环

  1. 自发不回放：Bot 自己发出的消息，不会作为事件回放到自己的事件队列
  2. grantor outbound 不 fan 给其 bot：被授权（grantor）Bot 的代发消息，不再 fan-out 给 grantor 自己
  3. `__obo_processed__` 标记幂等短路：代发消息携带保留键 `__obo_processed__`，服务端识别后幂等短路，拒绝伪造

⚠️ `__obo_processed__` 是服务端保留键，客户端/Bot 伪造会被拒绝。

7.3 级联深度

  • ❌ 无显式级联深度计数器 / 最大 hop 数 / 多 Bot 互@熔断机制（Q9 BA-05 待私有仓确认）
  • 当前防循环完全靠上述 __obo_processed__ 标记，不是基于 hop 深度计数

8. 常见问题（FAQ）

Q: Bot 怎么收消息？WebSocket 还是 Webhook？

Q: Bot Token 是什么格式？我看到的示例是 `bt_` 开头对吗？

Q: Bot 可以监听群成员加入/退出/表情回应吗？

Q: Bot 可以读写网盘文件吗？

Q: Bot 加群后是管理员吗？

Q: Bot 能改群头像/禁言/设管理员吗？

Q: bot_token 泄露了怎么办？

Q: Bot 可以在多少个群里使用？

Q: Bot 和 Marketplace 插件（skill/connector）是什么关系？

Q: Bot 怎么接收文档评论中的@提醒？

Q: Bot 能发互动卡片吗？能动态改卡吗？

Q: Bot 能直接创建/编辑文档吗？

Q: 两个 Bot 能互相调用吗？会不会无限循环？

Q: App Bot 和 User Bot 有什么区别？

9. 待确认项清单（Q9 后剩余）

9.1 🔬 Q9 标 ❌（需运行时 config 或私有仓确认）

编号 待确认项 优先级 影响
BA-07 business 桶具体 RPS/日配额默认值（system_setting 动态配置，源码无硬编码） P1 §4.2 限流
BA-HOP Bot 级联深度计数器 / 最大 hop 数 / 多 Bot 互@熔断（当前靠 __obo_processed__ 标记，非深度计数） P2 §7.3 互调
BA-VOICE 语音消息收发/语音转写 API 详细端点与 payload P2 §6.4/§6.5

9.2 📝 非 P0 流程/细节（不阻塞 v1.0 开发与售前）

编号 待确认项 影响章节
BA-01 BotFather 创建入口/自助步骤/审批流程 §2.1
BA-03 App Bot scope 完整枚举 §2.2
BA-05 安装 Bot 到群的完整自助流程 §3
BA-06 register/heartbeat 完整 payload + WuKongIM 连接参数（host/port/protocol） §4.3
BA-11 语音纠错 API 完整方法（GET/POST/PUT/DELETE）+ payload §6.5
BA-12 搜索 API payload/范围/分页/返回格式 §6.6
BA-GROUPS 群组/Thread/Webhook/typing/已读/@ 等端点的完整路径与 payload 清单 §6.3/§6.4（已转入《Bot-API概览》逐端点展开）
BA-DOCSAPI octo-cli 调 docs API 的完整命令与参数 §6.9
BA-QUOTA Bot 加群数量配额 FAQ
BA-SEND 各消息 type 的 content 字段详细 schema §5.1（已转入《消息类型与发送-v1.0》专题文档）

端点路径/payload 级细节将在《Bot-API概览》逐端点文档中持续补全；消息类型 schema 由《消息类型与发送-v1.0》承载。

附录 A：相关文档

  • [Bot API 概览 v0.4 → 升级中](../04-api-integration/Bot-API概览.md) — 端点完整清单和源码证据
  • [消息类型与发送 v1.0](./消息类型与发送-v1.0.md) — 各消息 type 的 content schema 详解
  • [Webhook与事件订阅 v1.0](./Webhook与事件订阅-v1.0.md) — 群入站 Webhook 管理与事件详解
  • [安全权限与鉴权 v0.1](../99-archive/2026-09-22-v0x清零/安全权限与鉴权-v0.1.md) — 双token模型深度说明、三桶限流细节
  • [售前红线卡 v0.1](../08-presales-delivery/售前红线卡-v1.0.md) — Bot相关售前口径红线
  • [核心能力概览 v0.1](../01-product/核心能力概览.md) — 12个核心能力一览
  • [Drive网盘模块 v0.3](../01-product/模块说明/Drive网盘模块.md) — Bot对网盘零面证据链
  • [Docs协同模块](../01-product/模块说明/文档协同Docs模块.md) — 文档评论@Bot链路详情
  • [Q9 源码确认级原始回答](../00-inbox/product-bot-answers/2026-09-22-P1-r2-Q9-BotAPI与消息类型全景回答.md)

附录 B：版本记录

版本 日期 变更
v1.0 2026-09-22 Q9源码确认升级。①开头新增🔴三个售前易错点醒目框（HTTP长轮询/bf_前缀/收不到reaction和成员变动）；②鉴权：bf_/app_/uk_三类token前缀、bf_=16字节hex、Authorization: Bearer、Botfather /revoke（"Yes, revoke it"确认）、三桶限流+IP底线(register 100rps/heartbeat 500rps)；③事件接收：纠偏WebSocket/Webhook→HTTP长轮询POST /v1/bot/events(wait≤30s, Redis sorted-set+BLPOP)、5个事件源、App Bot仅DM、payload结构、收不到的事件清单；④发送消息：端点确认为POST /v1/bot/sendMessage、消息类型枚举补全(Const.ts)、互动卡片type=17双profile白名单/限制、动态改卡POST /v1/bot/message/edit+card_seq CAS；⑤管理能力清单：✅建群/改群名公告/加移除成员/Thread全套/群MD/typing/已读/消息编辑/文件上传下载/@/语音转写/Webhook/发私信；❌改头像/禁言/设管理员；⑥Bot间互调：无直接API、群消息fan-out、OBO三重防循环、无显式深度计数器；⑦文档创建/编辑需经octo-cli；⑧token泄露风险；⑨待确认项从26项压缩为3项Q9❌项+若干非P0细节。confidence 升 high。
v0.1 2026-09-22 框架版初版。基于Q1/Q2/Q4/Q6/Q7产品管家回答+源码事实，建立9章框架，26项待确认清单。文件API/鉴权模型/文档评论链路/网盘零面已确认；消息发送/事件接收/完整端点待Q9补全。
← 返回文档中心