Skip to content

Latest commit

 

History

History
194 lines (168 loc) · 8.59 KB

readme.md

File metadata and controls

194 lines (168 loc) · 8.59 KB

QQ 官方机器人 Java SDK

本文档介绍 SDK 的依赖、启动、事件监听、消息发送,以及 QQ 群机器人和自定义连接方式。

目录

快速开始

1. 准备应用凭据

登录 QQ 开放平台 创建机器人,获取 appid 和 secret。

2. 引入 SDK

项目依赖配置完成后即可使用,也可以浏览 Maven 仓库 获取版本信息。

3. 创建并启动机器人

Starter starter = new Starter("appid", "secret");
// 私域机器人:Intents.PRIVATE_INTENTS;公域机器人:Intents.PUBLIC_INTENTS
starter.getConfig().setCode(Intents.PRIVATE_INTENTS.getCode());
// 切换沙箱环境:starter.getConfig().sandbox();
starter.run();

项目结构

相关文档

事件监听

在 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);

Markdown

event.send(new Markdown("custom_template_id")
    .addParam("key", "value")
    .setKeyboard("id"));

QQ 群机器人

使用条件

当前 v2 群机器人能力需要满足:

  1. 机器人类型为公域机器人。
  2. 已在QQ群配置页面完成权限配置。
  3. 群主从沙箱群“设置 → 群机器人”页面添加测试机器人。

公域机器人通常只有在被 @ 时才会触发群消息事件。

群管理 API

以下方法通过 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 对象调用。对应接口 自定义菜单与指令面板。

自定义菜单(仅 C2C 单聊)

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));
// ![分时K线 #800px #400px](qqbot-media://image/v1/xxx)

// 分页查询当前有效图片 / 删除(删除后引用立即失效,已发送消息不受影响)
bot.getMediaImages();                     // 第一页
bot.getMediaImages("cursor");             // 指定游标
bot.deleteMediaImage(image.getImageId());

// 消息事件监听器内也可直接通过事件调用(简单委托给 Bot)
// event.uploadImage("kline.png", bytes);
// event.getMediaImages();
// event.deleteMediaImage(image.getImageId());

配置连接方式

自定义 WebSocket 地址

已开通 Webhook 且无法继续使用 WebSocket 时,可使用Webhook 转 WebSocket 服务。设置 starter.getConfig().setWslink(...) 后按项目提供的监听器处理消息。

Webhook

Webhook 模式启用后,其他连接配置将失效。将回调地址设置为 https://your-domain/webhook0 ,确认部署机器可访问后,再设置服务端口:

// 0 表示不开启 Webhook
starter.getConfig().setWebhookport(81);

依赖兼容性

v1.5.0-Beta7 与 com.alibaba.fastjson2:fastjson2 同时引用时可能产生空指针异常,详见 Issue #20。