高级机器人与底层 API
这些接口让插件不局限于当前一条消息。所有能力仍受 QQ 官方权限、主动消息额度和平台安全限制。
机器人信息
js
const me = await ctx.getBotInfo();
const bots = await ctx.getBotList();群列表与状态
js
const groups = await ctx.getGroupList();
const info = await ctx.getGroupInfo(groupId);
const state = await ctx.getGroupBotState(groupId);
const mute = await ctx.getGroupMuteState(groupId);群成员
js
const res = await ctx.getGroupMembers(groupId);
for (const m of res.members ?? []) {
ctx.log(m.member_openid, m.username, m.member_role);
}分页:
js
let cursor = '';
do {
const page = await ctx.getGroupMembers(groupId, cursor);
// ...
cursor = page.next_cursor ?? '';
} while (cursor);消息历史
js
const history = await ctx.getMessageHistory(20);只读当前会话最近消息,返回方向、发送者、内容、事件类型、时间。
主动发送
js
await ctx.sendGroup(groupId, '主动群消息');
await ctx.sendPrivate(userId, '主动私聊');
await ctx.sendGroupMarkdown(groupId, '## 标题');
await ctx.sendPrivateMarkdown(userId, '## 标题');
await ctx.sendGroupMedia(groupId, url, 'image');
await ctx.sendPrivateMedia(userId, url, 'image');主动消息受每日额度/权限限制。
主动消息排障(重要)
先分清主动 / 被动:只有手里有 msg_id(用户刚发了消息)才能走被动回复,额度宽松、成功率高。以下场景没有 msg_id,只能发主动消息:
onGroupMemberAdd/onGroupJoinRequest(入群事件)onTimer定时任务- 支付回调、工作流推送等后台触发
主动消息最常见的失败是 40034105 主动消息失败, 无权限——不是你的代码错了,是这个群没开「接收机器人推送」:
| 排查步骤 | 做法 |
|---|---|
| 1. 查群状态 | await ctx.getGroupBotState(groupId),看 allow_proactive_msg 是否为 true |
| 2. 打开开关 | 手机 QQ → 进入该群 → 点机器人资料卡 → 打开「接收机器人推送」。这个开关只在手机 QQ 里,开放平台网页控制台没有 |
| 3. 验证 | 开关打开后立即生效,无需重启;可在群里发 群诊断 查看「可主动发消息」状态 |
为什么"开了插件却没反应"
入群验证、入群欢迎、定时播报这类插件全部依赖主动消息。群没开推送开关时,消息被 QQ 静默拒绝,现场表现就是"插件开了但群里毫无动静"。先查 allow_proactive_msg,再看事件日志,最后看服务日志里的错误码,别急着怀疑插件配置。
其他主动消息约束:
- 沙箱环境不支持主动私信(
sendPrivate类),上真机验证 - 主动消息有每日额度,超了同样失败
member_role=admin与allow_proactive_msg无关,管理员身份不会自动获得主动消息权限
ARK 卡片
js
await ctx.replyArk(23, [
{ key: 'title', value: '标题' },
]);需要先在 QQ 开放平台申请对应 ARK 模板。
AI
js
const answer = await ctx.aiChat('帮我总结这段话:' + ctx.content);
await ctx.reply(answer);使用当前机器人的 AI 配置;未配置会抛错。
底层 API
js
if (ctx.isOwner) {
const data = await ctx.callApi('GET', '/users/@me');
const groups = await ctx.callApi('GET', '/users/@me/groups');
}- 仅机器人主人
- 路径/参数按 QQ 官方 API
- 平台不保证所有官方接口都可用
- 不要用它绕过审核或做违规操作
命名空间
js
ctx.bot.info()
ctx.group.info()
ctx.group.members()
ctx.group.joinRequests()
ctx.private.send()接口失败怎么办
QQ 会返回错误码。先看:
- 机器人是否有权限
- 是否开通白名单
- 是否超过主动消息额度
- 目标群/用户是否仍存在
- 是否使用了错误的 openid
不要把原始错误直接暴露给普通群友,给可读提示。
