GoQQBot 使用文档
用 GoQQBot 可以接收 QQ 机器人事件、回复消息，也可以把按钮和富媒体接到自己的业务里。阅读时请对照当前仓库源码。项目要求 Go 1.24.4 或更高版本，具体以 go.mod 为准。
目录按 QQ 官方 API v2 划分，参考 Gin 的使用文档，每页讲清一项任务。各页通过示例说明 SDK 的用法，完整字段表见官方文档。
开始使用
- 安装 SDK，或使用本地
replace引用本地 SDK 源码。 - 运行第一个机器人，选择 WebSocket 或 Webhook。
- 注册命令与普通消息，让不同类型的事件共用一个处理函数。
- 发送 Markdown 和按钮，再接入自己的业务服务。
起步指南
按接入阶段查找配置和运行方法。
| 主题 | 页面 |
|---|---|
| 启动接入 | 安装、快速开始 |
| 获取访问凭证 | Access Token 与凭证 |
| API 调用指南 | 客户端、超时与错误 |
| 事件订阅与通知 | 概述、WebSocket、Webhook |
| SDK 配置与生命周期 | 配置参考、运行与关闭 |
服务端接口
按消息场景或管理任务查找接口。
| 官方模块 | 文档 |
|---|---|
| 消息收发 | 概述、单聊、群聊、频道 |
| 消息类型 | 纯文本、Markdown、图文卡片、ARK |
| 引用和撤回 | 消息索引、回复来源和撤回 ID |
| 富文本接收 | 图片、表情、ARKData、MsgElement 和 MessageScene |
| 流式消息 | 单聊顺序更新 |
| 消息交互 | 概述、按钮、回调、文本交互 |
| 富媒体消息 | 概述、单聊、群聊、分片步骤 |
| 素材管理 | Markdown 图片上传、复用、查询和删除 |
| 机器人 | 资料与频道列表、分享和事件、菜单及指令面板 |
| 群聊管理 | 概述、成员、入群审批 |
| 频道管理 | 概述、资料及子频道、成员与权限、内容 |
日志、业务接入和测试
完成接入后，可按业务需要查看以下页面。
如果某个管理接口还没有现成的 SDK 方法，对应条目会给出官方文档或直接调用的示例。
文档维护
左侧导航来自 _Sidebar.md。文档里的 Go 示例均可独立编译：
package guide示例可放入业务包。- 标注完整程序的
package main示例可单独运行。 - 示例通过函数参数或本地配置接收参数。
在仓库根目录运行下面的命令，检查链接和代码块。脚本会在临时模块中通过本地 replace 引用当前 SDK，再编译 Go 示例。
sh
python wiki/_tools/check_docs.pySDK rules记录项目维护规范。历史核对记录见 docs。
注意事项
- 管理类示例中的原始调用不代表 SDK 已提供完整封装。
- 平台权限、消息审核、客户端显示及接口配额由 QQ 平台决定。
- 检查脚本不连接机器人，也不发消息。编译通过只表示示例与当前 SDK 兼容。QQ 实机联调需另外执行。