Skip to content

公共 API ​

机器人的基础 API 接口,包括机器人信息获取、文件上传、操作响应等通用功能。

🤖 机器人信息 ​

获取机器人信息 ​

获取当前机器人的基本信息。

方法名: bot.botService.getSelfInfo() / bot.getSelfInfo()

返回类型: Promise<ApiResponse<Bot.Info>>

typescript
// 使用服务模块(推荐)
const result = await bot.botService.getSelfInfo()
if (result.success) {
    console.log('机器人信息:', result.data)
}

// 使用传统方法(向后兼容)
const botInfo = await bot.getSelfInfo()

返回数据结构:

typescript
interface Bot.Info {
    id: string              // 机器人 ID
    username: string        // 机器人用户名
    avatar: string          // 机器人头像 URL
    union_openid?: string   // 联合身份标识
    union_user_account?: string // 联合用户账号
}

获取用户基本信息 ​

获取单聊用户的昵称、头像,以及是否允许机器人主动推送(2026-11-16 新增,10 QPS)。用户与机器人无好友关系时返回错误码 40184001。

方法名: bot.botService.getUserInfo(user_openid) / bot.getUserInfo(user_openid) / bot.user(user_openid).info()

typescript
const info = await bot.getUserInfo(user_openid)
if (info.allow_proactive_msg) {
    await bot.sendPrivateMessage(user_openid, `你好,${info.username}`)
}

返回数据结构:

typescript
interface UserBasicInfo {
    username: string              // 用户名
    avatar: string                // 头像原图 URL
    allow_proactive_msg: boolean  // 是否接收主动推送
    union_openid?: string         // 跨应用关联 openid,绑定第三方应用时有效
}

官方文档:获取用户基本信息

生成分享链接 ​

生成邀请用户添加机器人为好友的分享链接。callback_data 会在用户通过链接添加机器人时透传给机器人后台,最长 32 字符。

方法名: bot.botService.generateUrlLink(options?) / bot.generateUrlLink(options?)

typescript
const result = await bot.generateUrlLink({
    callback_data: 'campaign_20260916',
})

console.log(result.data.url)

请求与响应类型:

typescript
interface GenerateUrlLinkOptions {
    callback_data?: string
}

interface GenerateUrlLinkResponse {
    data: {
        url: string
    }
}

官方文档:生成分享链接

发送选项 ​

MessageService 和 Bot 的 sendPrivateMessage / sendGroupMessage / sendGuildMessage / sendDirectMessage 均接受可选的第 4 个参数 options。实体的 send(message, source?, options?) 使用相同选项;WebSocket、Webhook 模式均适用。

typescript
import type { SendOptions } from 'qq-official-bot'

const options: SendOptions = { msgSeq: 1, timeout: 10000 }
await bot.sendGroupMessage(group_id, '第一次回复', { id: original_message_id }, options)
await bot.sendGroupMessage(group_id, '第二次回复', { id: original_message_id }, { msgSeq: 2 })
字段类型说明
msgSeqnumber请求体中的 msg_seq;不传时保留随机生成的行为
timeoutnumber发送请求超时,单位毫秒;默认 10000
isWakeupboolean作为互动召回消息发送(仅单聊),与被动回复互斥

单聊/群聊的 msg_id 与 event_id 二选一:source 同时带有 id 和 event_id 时,SDK 只发送 msg_id(频道接口保持原行为)。

发送结果 SendResult 包含:id、timestamp(平台返回的发送时间,Unix 秒)、ref_idx(单聊/群聊引用索引,可用于引用机器人自己的消息)。

同一 msg_id 的不同回复由调用方递增 msgSeq;同一次发送超时后若决定重试,应复用原来的 source、消息内容和 msgSeq。SDK 仅透传指定序号,不自动计数或重试。未提供序号时仍使用随机值。

官方规则:消息收发概述。

📁 文件上传 ​

群聊、单聊的图片/视频/语音/文件需先上传拿到 file_info,再以 msg_type=7 发送。官方推荐分片上传;公网可访问的地址仍可用 URL 转存。频道消息不受此流程影响。

官方文档:富媒体消息概述

方式适用行为
URL 转存http(s):// 公网文件POST .../files,平台下载转存
分片上传本地路径 / Buffer / Base64预上传 → PUT 分片 → 确认分片 → 合并

单聊与群聊上传互不通用,必须对对应会话上传。

上传富媒体文件 ​

方法名: bot.fileProcessor.uploadMedia(fileData, options) / bot.uploadMedia(targetId, targetType, fileData, options?)

参数:

参数名类型必填描述
targetIdstring✅用户 OpenID 或群 OpenID
targetType'user' | 'group'✅上传场景
fileDatastring | Buffer✅本地路径、http(s) URL、Base64 或 Buffer
options.fileType1 | 2 | 3 | 4❌1 图片、2 视频、3 语音、4 文件;可按扩展名推断
options.fileNamestring❌文件名
options.sendMessageboolean❌true 时上传后直接发送(占用主动消息频次)
options.forceChunkedboolean❌即使是 URL 也先下载再走分片

文件数据格式:

  • 本地文件: /path/to/file.jpg 或 file:///path/to/file.jpg
  • 网络 URL: https://example.com/image.jpg
  • Base64: base64://... 或 data:image/jpeg;base64,...
  • Buffer: 直接传入 Buffer
typescript
// 本地文件:自动走分片上传
const local = await bot.uploadMedia(group_id, 'group', './demo.mp4', {
    fileType: 2,
    fileName: 'demo.mp4',
})
console.log(local.file_info, local.ttl, local.raw_url)

// 公网 URL:平台转存
const remote = await bot.uploadMedia(user_id, 'user', 'https://example.com/image.jpg', {
    fileType: 1,
})

// 发消息时本地图片也会自动分片上传
await bot.sendGroupMessage(group_id, segment.image('./photo.png'))

发送消息时一般不必手动上传:sendGroupMessage / sendPrivateMessage 遇到本地文件会先分片上传,再带 media.file_info 发出。

底层也可分步调用:

typescript
const prepared = await bot.fileProcessor.prepareUpload('group', group_id, {
    file_type: 2,
    file_size: String(buffer.length),
    file_name: 'demo.mp4',
    md5,
    sha1,
    md5_10m,
})
// PUT prepared.parts[i].presigned_url 后调用 finishUploadPart
// 全部完成后 completeUpload 拿到 file_info

返回数据结构:

typescript
interface FileUploadResult {
    file_uuid: string       // 文件唯一标识
    file_info: string       // 发送消息时透传到 media.file_info
    ttl: number             // 有效期(秒),0 表示可长期使用
    id?: string             // 仅 srv_send_msg=true 时返回
    raw_url?: string        // 分片上传合并后的预签名下载地址(图片/视频/语音)
}

🎯 操作响应 ​

响应操作事件 ​

响应用户的交互操作(如按钮点击、表单提交等)。

方法名: bot.botService.replyAction(actionId, code?) / bot.replyAction(actionId, code?)

参数:

参数名类型必填描述
actionIdstring✅操作 ID
codeActionNoticeEvent.ReplyCode❌响应码,默认为 0

响应码说明:

typescript
enum ReplyCode {
    SUCCESS = 0,           // 操作成功
    FAILED = 1,            // 操作失败
    INVALID = 2,           // 无效操作
    FORBIDDEN = 3,         // 操作被禁止
    TIMEOUT = 4            // 操作超时
}
typescript
// 响应成功
await bot.botService.replyAction(action_id, 0)

// 响应失败
await bot.botService.replyAction(action_id, 1)

// 使用枚举
import { ActionNoticeEvent } from 'qq-official-bot'
await bot.botService.replyAction(action_id, ActionNoticeEvent.ReplyCode.SUCCESS)

🔗 机器人生命周期 ​

启动机器人 ​

启动机器人并建立与 QQ 服务器的连接。

方法名: bot.start()

typescript
await bot.start()
console.log('机器人启动成功')

// 监听启动事件
bot.on('ready', () => {
    console.log(`机器人 ${bot.nickname} 已上线`)
})

停止机器人 ​

停止机器人并断开与 QQ 服务器的连接。

方法名: bot.stop()

typescript
await bot.stop()
console.log('机器人已停止')

// 监听停止事件
bot.on('offline', () => {
    console.log('机器人已下线')
})

🔧 工具方法 ​

配置定义 ​

使用类型安全的配置定义。

方法名: defineConfig(config)

typescript
import { defineConfig, ReceiverMode } from 'qq-official-bot'

const config = defineConfig({
    appid: 'your_app_id',
    secret: 'your_app_secret',
    mode: ReceiverMode.WEBSOCKET,
    intents: ['GUILD_MESSAGES'],
    sandbox: false,
    logLevel: 'info',
})

const bot = new Bot(config)

创建机器人实例 ​

快速创建机器人实例的工厂方法。

方法名: createBot(config)

typescript
import { createBot, ReceiverMode } from 'qq-official-bot'

const bot = createBot({
    appid: 'your_app_id',
    secret: 'your_app_secret',
    mode: ReceiverMode.WEBSOCKET,
    intents: ['GUILD_MESSAGES'],
})

await bot.start()

📊 状态信息 ​

获取连接状态 ​

获取机器人的当前连接状态。

typescript
// 获取机器人 ID
console.log('机器人 ID:', bot.self_id)

// 获取机器人昵称
console.log('机器人昵称:', bot.nickname)

// 获取连接状态
console.log('连接状态:', bot.status)

// 检查是否在线
const isOnline = bot.status === 1

日志管理 ​

机器人内置了完整的日志系统。

typescript
// 设置日志级别
bot.logger.level = 'debug'

// 输出不同级别的日志
bot.logger.trace('追踪信息')
bot.logger.debug('调试信息')
bot.logger.info('一般信息')
bot.logger.warn('警告信息')
bot.logger.error('错误信息')

⚠️ 注意事项 ​

  1. 异步操作: 所有 API 方法都是异步的,请使用 await 或 .then() 处理
  2. 错误处理: 建议使用服务模块的方法,它们提供统一的错误处理
  3. 文件限制: 文件上传有大小限制,请查阅官方文档了解具体限制
  4. 生命周期: 确保在适当的时机调用 start() 和 stop() 方法