Skip to content

高级机器人与底层 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

不要把原始错误直接暴露给普通群友,给可读提示。

薇薇官机平台 · ZL 系列插件