本文档介绍 SDK 的依赖、启动、事件监听、消息发送,以及 QQ 群机器人和自定义连接方式。
登录 QQ 开放平台 创建机器人,获取 appid 和 secret。
项目依赖配置完成后即可使用,也可以浏览 Maven 仓库 获取版本信息。
Starter starter = new Starter("appid", "secret");
// 私域机器人:Intents.PRIVATE_INTENTS;公域机器人:Intents.PUBLIC_INTENTS
starter.getConfig().setCode(Intents.PRIVATE_INTENTS.getCode());
// 切换沙箱环境:starter.getConfig().sandbox();
starter.run();- api:SDK 功能定义
- entities:QQ 官方数据结构
- http:HTTP 请求工具
- impl:API 基础实现
- network:网络连接层
- utils:工具类
- Resource.java:公共资源
- Starter.java:启动入口
- Start0.java:启动附属组件
在 Starter#run() 后注册监听器。监听方法参数可以是任意 Event 子类或实现类,且必须添加 @EventReceiver 注解。
starter.registerListenerHost(new ListenerHost() {
@EventReceiver
public void onEvent(MessageEvent event) {
event.send("Hello World!");
}
});MessageEvent 实现了发送能力,可直接调用 send。
sender.send("文本");Image image = new Image(url); // 图片 URL
// Image image = new Image(bytes); // 图片字节
sender.send(image);event.send(new Markdown("custom_template_id")
.addParam("key", "value")
.setKeyboard("id"));当前 v2 群机器人能力需要满足:
- 机器人类型为公域机器人。
- 已在QQ群配置页面完成权限配置。
- 群主从沙箱群“设置 → 群机器人”页面添加测试机器人。
公域机器人通常只有在被 @ 时才会触发群消息事件。
以下方法通过 Group 对象调用。事件中可使用 GroupEvent#getGroup() 或 GroupMessageEvent#getSubject() 获取群对象。
Group group = event.getGroup();
String memberOpenid = "member-openid";
System.out.println(group.getInfo());
System.out.println(group.getBotState());
System.out.println(group.getJoinRequestList());
System.out.println(group.getJoinRequestList(null, 50));
group.approvalJoinRequest(memberOpenid, new JoinApproval().setOp("approve"));
System.out.println(group.getMuteSetting());
group.muteMember(memberOpenid, Mute.Add, 60);
// 解除禁言:group.unmuteMember(memberOpenid)getJoinRequestList(cursor, limit) 返回 JoinRequestList,可通过 getList() 获取申请列表、getNextCursor() 获取下一页游标。审批支持 ifApprove / ifDecline 条件方法;muteMember 支持 Mute.Add、Mute.Update,群禁言可通过 setMuteSetting(...) 设置。
MessageAsyncBuilder builder = new MessageAsyncBuilder();
builder.image("https://kloping.top/icon.jpg");
builder.text("主动消息测试");
bot.sendMessage("474905EE5C4F5199A1EC08E1C04BF077", builder.build());以下能力均为应用级配置,通过 Bot 对象调用。对应接口 自定义菜单与指令面板。
Bot bot = starter.getBot();
// 查询当前菜单
MenuData data = bot.getMenu();
// 修改菜单(覆盖原有完整配置)
bot.setMenu(new Menu().setItems(Arrays.asList(
new Menu.MenuItem().setType(Menu.TYPE_SEND_MESSAGE).setName("帮助").setSendMessage("/help"),
new Menu.MenuItem().setType(Menu.TYPE_LINK).setName("官网").setLink("https://example.com"),
new Menu.MenuItem().setType(Menu.TYPE_SWITCH).setName("搜索")
.setSwitchConfig(new Menu.SwitchConfig().setSwitchId("search").setDefaultOn(true)))));支持 c2c(单聊)、group(群聊)、channel(文字子频道)、dm(频道私信)四种场景,其中 c2c/group 支持按指定用户/群生效。
// 创建 group 指定群面板
Panel.Created created = bot.createPanel(new Panel.CreateRequest()
.setScope(Panel.SCOPE_GROUP)
.setTargetType(Panel.TARGET_SPECIFIC)
.setGroupOpenids(Collections.singletonList("group-openid"))
.setPanel(new Panel().setItems(Collections.singletonList(
new Panel.PanelItem().setType(Panel.TYPE_COMMAND).setName("群签到").setDesc("每日签到")))));
String panelId = created.getPanelId();
// 分页查询面板列表 / 查询详情
bot.getPanels(Panel.SCOPE_GROUP); // 第一页
bot.getPanels(Panel.SCOPE_GROUP, null, 50); // 指定游标与条数
bot.getPanel(panelId);
// 修改面板配置(不影响已关联的用户/群)
bot.updatePanel(panelId, new Panel().setRemark("更新备注").setItems(Collections.singletonList(
new Panel.PanelItem().setType(Panel.TYPE_COMMAND).setName("群签到").setDesc("每日签到"))));
// 增删面板关联对象(仅 c2c/group 的 specific 面板)
bot.updatePanelTarget(panelId, new Panel.TargetRequest()
.setOp(Panel.OP_ADD).setGroupOpenids(Collections.singletonList("another-group")));
// 删除面板
bot.deletePanel(panelId);预上传 Markdown 图片,换取 qqbot-media:// 引用链接后在 Markdown 消息中反复引用。对应接口 素材管理。
限制:单图不超过 10MB,仅支持 png/jpeg/gif/webp;单机器人上限 100 张(删除可释放);引用滑动过期,每次被消息成功引用后 90 天顺延。
Bot bot = starter.getBot();
// 上传(内部依次执行申请上传、直传预签名地址、完成上传)
// complete 接口仅返回 image_id、url、ttl、preview_url,其余字段按入参与本机时间补齐(近似值)
MediaImage image = bot.uploadImage("kline.png", bytes);
// 生成 Markdown 引用并发送
Markdown markdown = Markdown.ofText(image.toMarkdown("分时K线", 800, 400));
// 
// 分页查询当前有效图片 / 删除(删除后引用立即失效,已发送消息不受影响)
bot.getMediaImages(); // 第一页
bot.getMediaImages("cursor"); // 指定游标
bot.deleteMediaImage(image.getImageId());
// 消息事件监听器内也可直接通过事件调用(简单委托给 Bot)
// event.uploadImage("kline.png", bytes);
// event.getMediaImages();
// event.deleteMediaImage(image.getImageId());已开通 Webhook 且无法继续使用 WebSocket 时,可使用Webhook 转 WebSocket 服务。设置 starter.getConfig().setWslink(...) 后按项目提供的监听器处理消息。
Webhook 模式启用后,其他连接配置将失效。将回调地址设置为 https://your-domain/webhook0 ,确认部署机器可访问后,再设置服务端口:
// 0 表示不开启 Webhook
starter.getConfig().setWebhookport(81);v1.5.0-Beta7 与 com.alibaba.fastjson2:fastjson2 同时引用时可能产生空指针异常,详见 Issue #20。