Java SDK

依赖

<dependency>
  <groupId>io.starim</groupId>
  <artifactId>bot-sdk</artifactId>
  <version>0.1.13</version>
</dependency>

要求 JDK 17+，包路径为 io.starim.botsdk.*。

环境变量

变量	说明
STARIM_BOT_TOKEN	sbot_…
STARIM_API_BASE	须含 /api/v1
STARIM_WEBHOOK_SECRET	Webhook secret_token

5 分钟：Webhook 回声

StarIMBot bot = StarIMBot.builder()
    .token(System.getenv("STARIM_BOT_TOKEN"))
    .baseUrl(System.getenv("STARIM_API_BASE"))
    .secretToken(System.getenv("STARIM_WEBHOOK_SECRET"))
    .build();

bot.command("start", ctx -> ctx.reply("你好"));
bot.on(UpdateType.MESSAGE, ctx -> {
  String text = ctx.getMessage().getText(); // 不是 content().text()
  if (text != null && !text.isBlank()) ctx.reply(text, true); // quote
});

bot.start(8787, "/webhook");
// 本地无公网：先 deleteWebhook，再 bot.startPolling(30);

两层 API

• StarIMBot：内置 JDK HttpServer Webhook + 长轮询；命令 / 事件路由。
• StarIMBotClient：直接调网关，适合无回调进程。

StarIMBotClient client = StarIMBotClient.builder()
    .token(System.getenv("STARIM_BOT_TOKEN"))
    .baseUrl(System.getenv("STARIM_API_BASE"))
    .build();

client.getMe();
client.sendMessage(new SendMessageParams("<chatId>", "hello")
    .setReplyToMessageId("<messageId>"));
client.sendPhotoFromFile("<chatId>", Path.of("photo.jpg"), "说明");

常用示例

先配置环境变量，再将所需示例加入你的项目。

export STARIM_API_BASE="https://<api-host>/api/v1"
export STARIM_BOT_TOKEN="sbot_..."
export STARIM_WEBHOOK_SECRET="与 setWebhook 时一致"

1. EchoBot（Webhook 回声）

StarIMBot bot = StarIMBot.builder()
    .token(System.getenv("STARIM_BOT_TOKEN"))
    .baseUrl(System.getenv("STARIM_API_BASE"))
    .secretToken(System.getenv("STARIM_WEBHOOK_SECRET"))
    .build();

bot.on(UpdateType.MESSAGE, ctx -> {
    String text = ctx.getMessage().getText();
    if (text != null && !text.isBlank()) ctx.reply(text);
});

int port = Integer.parseInt(System.getenv().getOrDefault("PORT", "8787"));
bot.start(port, "/webhook");
System.out.println("listening http://0.0.0.0:" + port + "/webhook");

2. SlashCommand（/start /help）

bot.command("start", ctx -> ctx.reply("欢迎使用 StarIM 机器人（官方 Java SDK 示例）"));
bot.command("help", ctx -> ctx.reply("可用命令：/start /help"));
bot.on(UpdateType.MESSAGE, ctx -> {
    String text = ctx.getMessage().getText();
    if (text != null && !text.startsWith("/")) ctx.reply("发送 /help 查看帮助");
});
bot.start(8788, "/webhook");

3. SendPhoto（本地图片脚本）

StarIMBotClient client = StarIMBotClient.builder()
    .token(System.getenv("STARIM_BOT_TOKEN"))
    .baseUrl(System.getenv("STARIM_API_BASE"))
    .build();

Object res = client.sendPhotoFromFile(
    System.getenv("STARIM_CHAT_ID"),
    Path.of(args[0]),
    "from io.starim:bot-sdk (java)");
System.out.println("sendPhoto OK: " + res);

4. 长轮询

// 先 deleteWebhook
bot.command("start", ctx -> ctx.reply("hi from polling"));
bot.startPolling(30);

方法对照（点链接看参数）

场景	SDK 方法	文档
身份 / Profile	getMe、setMyCommands、setMyShortDescription…	机器人信息
发送	sendMessage、sendPhoto…、sendPhotoFromFile、uploadFile	消息发送 · 文件
编辑转发	editMessage、forwardMessage、copyMessage（支持 caption）	编辑与转发
投递	setWebhook、getUpdates、startPolling	Webhook
会话	getMyChats、getChat*、置顶 / 改群名	群读取
治理	kickChatMember / banChatMember / unbanChatMember	群治理
调度成员	listChatVirtualMembers、simulateSendMessage	调度成员（需开通）

HTTP 契约全文：API 索引（含 JWT 控制台接口怎么接）。

下一步

5 分钟上手 · Node SDK · API 索引。