Node.js SDK

安装

pnpm add @starim-io/bot-sdk
# 或 npm i @starim-io/bot-sdk

要求 Node.js ≥ 18。

环境变量

变量	说明
SOCHAT_BOT_TOKEN / STARIM_BOT_TOKEN	审核通过后的 sbot_…
SOCHAT_API_BASE / STARIM_API_BASE	网关前缀，必须含 /api/v1
SOCHAT_WEBHOOK_SECRET	与 setWebhook.secret_token 一致，用于验签

5 分钟：长轮询回声

import { StarIMBot } from '@starim-io/bot-sdk'

const bot = new StarIMBot({
  token: process.env.SOCHAT_BOT_TOKEN!,
  baseUrl: process.env.SOCHAT_API_BASE!, // https://<api-host>/api/v1
  secretToken: process.env.SOCHAT_WEBHOOK_SECRET,
})

bot.command('start', (ctx) => ctx.reply('你好，我是机器人'))
bot.on('message', async (ctx) => {
  const text = ctx.message?.text
  if (text) await ctx.reply(text, { quote: true }) // 引用回复
})

// 本地调试：先在控制台 / API 删除 Webhook，再：
await bot.startPolling()
// 有公网 HTTPS：await bot.start({ port: 8787, path: '/webhook' })

两层 API

• 高阶 StarIMBot：command / on / start / startPolling；上下文里 ctx.reply、ctx.answerCallbackQuery。
• 低阶 StarIMBotClient（bot.client）：一对一封装网关 /api/v1/bots/**，适合脚本、定时任务、无 Webhook 场景。

import { StarIMBotClient } from '@starim-io/bot-sdk'

const client = new StarIMBotClient({
  token: process.env.SOCHAT_BOT_TOKEN!,
  baseUrl: process.env.SOCHAT_API_BASE!,
})

const me = await client.getMe()
await client.sendMessage({
  chat_id: '<conversationId>',
  text: 'hello',
  reply_to_message_id: '<messageId>', // 可选引用
  reply_markup: {
    inline_keyboard: [[{ text: '收到', callback_data: 'ack' }]],
  },
})

// 一次调用上传并发送本地图片
await client.sendPhotoFromFile('<chat_id>', './photo.jpg', { caption: '说明' })

常用示例

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

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

1. 回声机器人（Webhook）

文件 echo-bot.ts：收到文本原样回复。

import { StarIMBot } from '@starim-io/bot-sdk'

const bot = new StarIMBot({
  token: process.env.STARIM_BOT_TOKEN!,
  secretToken: process.env.STARIM_WEBHOOK_SECRET!,
  baseUrl: process.env.STARIM_API_BASE,
})

bot.on('message', async (ctx) => {
  const t = ctx.message.text?.trim()
  if (t) await ctx.reply(t)
})

const port = Number(process.env.PORT || 8787)
await bot.start({ port, path: '/webhook' })
console.log('listening http://0.0.0.0:' + port + '/webhook')

将公网 HTTPS 地址指向该 Webhook，并在控制台完成配置。

2. 斜杠命令

文件 slash-command.ts：/start、/help。

bot.command('start', async (ctx) => {
  await ctx.reply('欢迎使用 StarIM 机器人（官方 Node SDK 示例）')
})
bot.command('help', async (ctx) => {
  await ctx.reply('可用命令：/start /help')
})
bot.on('message', async (ctx) => {
  if (ctx.message.text?.startsWith('/')) return
  await ctx.reply('发送 /help 查看帮助')
})
await bot.start({ port: 8788, path: '/webhook' })

3. 发本地图片（脚本，无需 Webhook）

使用低阶 Client 一步上传并发送。

import { StarIMBotClient } from '@starim-io/bot-sdk'

const client = new StarIMBotClient({
  token: process.env.STARIM_BOT_TOKEN!,
  baseUrl: process.env.STARIM_API_BASE,
})

await client.sendPhotoFromFile(
  process.env.STARIM_CHAT_ID!, // 会话 conversationId
  process.argv[2]!,           // 图片路径
  { caption: '来自 @starim-io/bot-sdk' },
)

4. 本地长轮询（无公网时）

// 先 deleteWebhook，再：
import { StarIMBot } from '@starim-io/bot-sdk'
const bot = new StarIMBot({
  token: process.env.STARIM_BOT_TOKEN!,
  baseUrl: process.env.STARIM_API_BASE!,
})
bot.command('start', (ctx) => ctx.reply('hi from polling'))
bot.on('message', async (ctx) => {
  if (ctx.message?.text) await ctx.reply(ctx.message.text, { quote: true })
})
await bot.startPolling()

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

下列方法均可通过 client.* 调用。

场景	SDK 方法	文档
身份	getMe	机器人信息
发文本 / 媒体	sendMessage、sendPhoto…、sendPhotoFromFile	消息发送 · 文件
编辑 / 删 / 转	editMessage、deleteMessage、forwardMessage、copyMessage	编辑与转发
Webhook / 轮询	setWebhook、deleteWebhook、getUpdates、startPolling	Webhook · 长轮询
会话	getMyChats、getChat*、置顶 / 改群资料	群读取 · 群写入
治理	kickChatMember / ban / unban	群治理
Inline	answerCallbackQuery、answerInlineQuery	富交互 · 指南
调度成员	listChatVirtualMembers、simulateSendMessage	调度成员（需开通）

完整路径清单见 API 索引；控制台申请 / JWT 接口也在该页「开发者控制台 API」。

Webhook 验签（自建 HTTP 时）

平台头：X-StarIM-Signature-V2、X-StarIM-Timestamp。签名串为 timestamp + "." + rawBody。务必用原始请求字节验签；用 StarIMBot.start() 时 SDK 已内置。

下一步

5 分钟上手 · 鉴权 · API 索引。