API 总览

获取当前在线 Bot 的登录号、昵称和客户端协议。

调用

const info = await api.get_login_info(self_id)

参数

返回值

{
  user_id: 123456789,
  nickname: '示例账号',
  client_type: 'android',
}

client_type 为 android 或 linux。接口只读取框架进程内的账号状态，不会发起 QQ 协议请求，也不会返回密码、登录票据或其他敏感身份信息。

const targetApi = api.forProtocol('linux') // 或 'android'

获取当前在线 Bot 的连接状态与基础运行计数。

调用

const status = await api.get_status(self_id)

参数

返回值

{
  online: true,
  good: true,
  client_type: 'android',
  stat: {
    packet_received: 1024,
    packet_sent: 128,
    online_time: 3600,
  },
}

online 只有在账号状态为在线且本地 MSF 连接处于已连接状态时才为 true。统计值直接来自框架进程内运行数据，不额外向 QQ 服务端查询。

const targetApi = api.forProtocol('linux') // 或 'android'

获取萌卡 NT 框架版本、插件协议版本和当前账号协议。

调用

const version = await api.get_version_info(self_id)

参数

返回值

{
  app_name: 'Mengka-NT',
  protocol_version: 'v11',
  app_version: 'x.y.z',
  client_type: 'linux',
}

app_version 使用当前运行二进制的框架版本，不写死在 SDK 中；client_type 为当前账号的 android 或 linux 平台。

const targetApi = api.forProtocol('linux') // 或 'android'

检查当前在线 Bot 是否具备图片发送能力。

调用

const result = await api.can_send_image(self_id)

参数

返回值

{ yes: true }

使用 api.forProtocol('android' | 'linuxqq') 选择账号协议，框架按账号实际节点路由并检查在线状态。v2.0.6 此能力标志仍对 Android 返回 true、Linux 返回 false，并非逐种消息场景的探测结果。

注意：Linux 群图片发送链路已在 v2.0.6 修复并实测，但此标志尚未同步，不能把 false 解释为所有 Linux 图片接口都不支持。接入方应结合具体发送接口的协议说明及实际结果判断；好友图片上传全链路未包含在已完成的实测范围内。

const targetApi = api.forProtocol('linux') // 或 'android'

检查当前在线 Bot 是否具备语音发送能力。

调用

const result = await api.can_send_record(self_id)

参数

返回值

{ yes: true }

使用 api.forProtocol('android' | 'linuxqq') 选择账号协议，框架按账号实际节点路由并检查在线状态。v2.0.6 此能力标志对 Android 返回 true、Linux 返回 false。这是框架本地能力标志，不会发出测试语音，也不是任意语音编码、上传或转换流程的成功保证。

const targetApi = api.forProtocol('linux') // 或 'android'

将公开 HTTP(S) 地址的文件下载到萌卡 NT 框架目录下，并返回后端可直接读取的本地绝对路径。该接口是框架级接口，不需要 self_id。

调用

const result = await api.download_file({
  url: 'https://example.com/files/example.zip',
  headers: {
    Authorization: 'Bearer example-token',
  },
})

参数

返回值

{
  file: '/framework/data/plugin-downloads/随机前缀-example.zip',
}

文件始终保存在框架目录的 data/plugin-downloads 中，不会写入系统临时目录或框架目录之外。单个文件最大 128 MiB，最多跟随 5 次重定向；本机、内网和保留网段地址会被拒绝，防止插件借下载接口访问框架内部服务。

下载失败时会返回明确的 HTTP 状态、文件大小或地址安全错误，不会保留未完成的 .part 文件。

按 stream_id 分片上传文件。新流必须填写 total_chunks，每个分片填写 Base64 chunk_data 与从 0 开始的 chunk_index。分片可乱序，重复提交相同分片不会重复计数。

await api.upload_file_stream({
  stream_id: 'job-1', total_chunks: 2, chunk_index: 0,
  chunk_data: 'SGVsbG8g', file_size: 11, filename: 'hello.txt'
})
await api.upload_file_stream({ stream_id: 'job-1', chunk_index: 1, chunk_data: 'V29ybGQ=' })
const result = await api.upload_file_stream({ stream_id: 'job-1', is_complete: true })

可选 expected_sha256 用于完整性校验，verify_only 查询状态，reset 清理未完成流。file_retention 单位毫秒，默认 5 分钟，填 0 表示不自动删除完成文件。未完成流 10 分钟无活动会自动回收，所有文件均限定在框架目录的 data/stream-temp。

清理全部未完成流和框架目录 data/stream-temp 中的流式传输文件，不影响其他媒体缓存。

await api.clean_stream_temp_file({})

发送 10 个 data_chunk 测试帧，随后返回 data_complete，用于检查插件的流式帧消费逻辑。

await api.test_download_stream({ error: false })

传 error: true 时，10 个测试帧发送完毕后返回失败响应。

以 action_stream 分片帧下载文件。该接口只读取明确传入的安全来源，不查询 QQ 群文件、私聊文件或媒体服务。

参数

file_id 不受支持。只传 file_id 会直接失败，框架不会回退调用 QQ 文件接口。文件总大小上限为 128 MiB；HTTP(S) 下载禁止本机、内网、保留网段和带凭据 URL。

const frames = []
const complete = await api.download_file_stream(
  { file: 'https://example.com/file.bin', chunk_size: 65536 },
  frame => frames.push(frame),
)

第一帧为 data_type=file_info，随后为一个或多个 Base64 file_chunk；Promise 最终返回 data_type=file_complete、总分片数和总字节数。

安全来源和分片顺序与 download_file_stream 相同。首个 file_info 额外返回图片 width、height；内容不能被识别为图片时请求失败。

await api.download_file_image_stream(
  { file: 'data:image/png;base64,iVBORw0KGgo...' },
  frame => console.log(frame),
)

该接口不接受仅有 file_id 的 QQ 媒体解析请求。

流式读取安全来源中的语音文件。参数和分片顺序与 download_file_stream 相同。

可选 out_format：mp3、amr、wma、m4a、spx、ogg、wav、flac。指定格式时由框架管理的 FFmpeg 容器完成转换，转换最多等待 2 分钟；未运行 FFmpeg 时会返回明确错误。

await api.download_file_record_stream(
  { file: 'https://example.com/voice.ogg', out_format: 'mp3' },
  frame => console.log(frame),
)

该接口不通过 file_id 查询 QQ 文件或媒体服务。

获取当前 QQ 账号的在线客户端列表。萌卡 NT 直接使用 QQ Android 9.2.70 下发的 RegisterProxy.PushParams 设备数据，不通过名称猜测，也不返回固定占位值。

const clients = await api.get_online_clients(106606)

参数

成功时直接返回客户端数组：

[
  {
    "app_id": 1,
    "device_name": "DESKTOP",
    "device_kind": "Windows",
    "client_type": 2,
    "state": 1,
    "platform_id": 3,
    "new_client_type": 2
  }
]

app_id、客户端类型、状态和平台字段来自 QQ 服务端；device_kind 优先使用服务端平台名称。账号刚登录且设备推送尚未到达时会返回空数组，收到推送后会自动更新。

const targetApi = api.forProtocol('linux') // 或 'android'

设置当前在线 Bot 的基础在线状态或 QQ 扩展状态。底层使用 QQ Android 9.2.70 的真实状态请求，不依赖 PC QQ。

调用

await api.set_online_status(self_id, status, ext_status, battery_status)

参数

数值参数同时接受 JSON number 和十进制字符串，便于兼容现有 OneBot/NapCat 插件。

返回值

成功返回 null。

示例

// 普通在线
await api.set_online_status(123456789, 10, 0, 0)

// 显示 76% 电量
await api.set_online_status(123456789, 10, 1000, 76)

// 离开
await api.set_online_status(123456789, 30, 0, 0)

const androidApi = api.forProtocol('android') // 省略时也默认 Android

设置当前在线 Bot 的自定义状态图标和文字。底层使用 QQ Android 9.2.70 的真实自定义状态请求。

调用

const message = await api.set_diy_online_status(
  self_id,
  face_id,
  face_type,
  wording,
)

参数

数值参数同时接受 JSON number 和十进制字符串。

返回值

返回 QQ 服务端给出的状态设置结果文字，例如：

set status success

示例

await api.set_diy_online_status(
  123456789,
  1,
  1,
  'API 验证',
)

需要恢复普通状态时，调用：

await api.set_online_status(123456789, 10, 0, 0)

const androidApi = api.forProtocol('android') // 省略时也默认 Android

向指定好友同步正在输入或结束输入状态。

调用

await api.set_input_status(self_id, user_id, event_type)

目标必须是当前账号的好友。成功返回空对象。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

查询指定 QQ 当前的基础在线状态和扩展状态。

调用

const status = await api.nc_get_user_status(self_id, user_id)

返回值包含 status、ext_status 等 QQ 服务端实时字段。好友隐私设置可能限制可见状态。

v2.0.6 修复（v2.0.6）

修复 Linux 账号按数字 QQ 查询时返回 316 的寻址参数错误，Android 和 Linux 均沿用本接口，无需增加参数或切换接口。此修复不在已发布的 v2.0.5 中。

公开状态不等同于框架内的登录状态；判断框架账号是否在线应查询 get_bot_list 或订阅账号上下线事件。本接口不提供陌生账号 UID，也不会触发好友申请事件。

const targetApi = api.forProtocol('linux') // 或 'android'

重启当前萌卡 NT 框架进程。调用成功后先返回 null，随后关闭本地 QQ 连接并保留缓存会话，再使用原启动参数重新启动框架。

该接口会短暂中断全部插件连接和管理页面请求，应只授予可信插件。

await api.set_restart({})

使用当前在线 Android QQ 登录态，请求 QQ 服务器判断网址安全等级。该接口会返回真实的服务端判定，不使用固定的“安全”占位值。

参数

返回值

{
  level: 1,
}

level 含义：

• 1：安全。
• 2：未知，QQ 服务器没有给出明确安全结果。
• 3：危险。

调用示例

{
  "action": "check_url_safely",
  "params": {
    "self_id": 1060221,
    "url": "https://www.qq.com/"
  }
}

使用 QQ Android 的批量翻译服务，将英文文本翻译为中文。

参数

返回值

{
  words: ["你好", "世界"],
}

返回列表与请求列表顺序一致；如果 QQ 服务器返回数量不匹配，框架会直接返回错误，不会用空文本补齐。

调用示例

{
  "action": "translate_en2zh",
  "params": {
    "self_id": 1060221,
    "words": ["hello", "world"]
  }
}

• action：send_packet
• 使用条件：已认证的正向或反向 WebSocket 服务，目标账号在线。托管和外部插件均可调用，无需白名单或专属 Key。

const responseHex = await api.send_packet(selfId, command, packetHex, true, reserveHex)
// Linux QQ 账号
const linuxResponse = await api.forProtocol('linuxqq').send_packet(selfId, command, packetHex)

参数

const responseHex = await api.call('send_packet', {
  self_id: selfId,
  client_type: 'android',
  cmd: command,
  data: packetHex,
  rsp: true,
})

command 和 packetHex 使用插件业务实际需要的协议与内容。

返回与错误

rsp=true 返回响应体的小写十六进制字符串；rsp=false 提交后返回 null。响应仍需按对应协议解析。

无效参数、账号离线、协议错误或超时会使调用失败。结果未知时先核对业务状态，不要自动重发。接口不再申请插件授权、读取专属 Key 或请求算法白名单服务；服务令牌认证、参数校验和账号路由继续生效。

基础连接见SDK 快速开始。

获取当前 QQ 账号与设备型号可用的在线机型显示名称。接口由萌卡 NT 后端直接使用当前账号的 Android 9.2.70 登录态、设备指纹和 QQ 会员机型服务完成。

const result = await api.get_model_show(1060221, 'Xiaomi 14 Pro')

参数

成功时返回：

{
  "variants": [
    {
      "model_show": "Xiaomi 14 Pro",
      "need_pay": false
    }
  ]
}

need_pay 表示该显示名称是否要求 QQ 会员权益。查询结果来自 QQ 服务端，不使用固定占位数据。

该接口复用框架现有 PsKey 能力后请求 QQ 会员 Web 服务，不增加新的 MSF/OIDB 命令。插件统一使用公开 action get_model_show。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

设置当前 QQ 账号的在线机型显示名称。接口由萌卡 NT 原生后端使用账号会话和设备指纹调用 QQ 服务，不依赖其他机器人框架。

await api.set_model_show(1060221, 'Xiaomi 14 Pro', 'Xiaomi 14 Pro')

参数

建议先调用 get_model_show 获取当前账号可用的显示名称，再选择 need_pay=false 或账号已具备权益的项目。成功时返回空数据。

该操作仅修改 QQ 展示机型，不修改框架设备指纹；传入空 model_show 可恢复 QQ 默认显示。插件统一使用公开 action set_model_show。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

发送群聊消息。

调用

const result = await api.send_group_msg(self_id, group_id, message)

参数

支持 text、reply、at、image、voice、video 和 face 等群聊消息段，详见消息段。

video 必须作为消息数组中的唯一消息段单独发送。

返回值

{
  success: true,
  message_id: 123456789,
  msg_seq: 123,
  msg_random: 456,
}

message_id 可直接用于后续引用回复；msg_seq 与 msg_random 可用于 recall_group_msg。

示例

await api.send_group_msg(123456789, 987654321, [
  { type: 'text', data: { text: '你好 🎉 [bq190]' } },
  { type: 'at', data: { uin: '112233445' } },
])

text 直接支持 Unicode emoji，并会把 [bq190] 解析为 QQ 自带的 190 号表情。需要精确控制表情消息段时，也可以使用 { type: 'face', data: { kind: 'qq_face', face_id: '190' } }。

引用回复

把收到的群消息事件或本接口返回的 message_id 放入 reply 段，即可发送 QQ 原生引用回复：

await api.send_group_msg(123456789, 987654321, [
  { type: 'reply', data: { message_id: event.message_id } },
  { type: 'text', data: { text: '已收到，我来处理。' } },
])

兼容 OneBot 写法 { type: 'reply', data: { id: event.message_id } }。引用消息必须属于当前群，一条消息只能包含一个 reply 段，且引用段后至少需要一个正文消息段。消息缓存过期后应重新从消息事件或历史消息接口获取 message_id。

const targetApi = api.forProtocol('linux') // 或 'android'

发送好友消息。

调用

const result = await api.send_friend_msg(self_id, user_id, message)

参数

返回值

{ success: true, message_id: 123456789, msg_seq: 123, msg_random: 456 }

示例

await api.send_friend_msg(123456789, 112233445, [
  { type: 'text', data: { text: '你好 🎉 [bq190]' } },
])

text 直接支持 Unicode emoji，并会把 [bq190] 解析为 QQ 自带的 190 号表情。结构化写法为 { type: 'face', data: { kind: 'qq_face', face_id: '190' } }。

user_id 必须使用 QQ 号，不接受 UID。

引用回复

把当前好友会话中消息事件的 message_id 放入 reply 段：

await api.send_friend_msg(123456789, 112233445, [
  { type: 'reply', data: { message_id: event.message_id } },
  { type: 'text', data: { text: '好的，已经看到了。' } },
])

也兼容 { type: 'reply', data: { id: event.message_id } }。引用消息必须属于当前好友会话，不能拿其他好友或群聊的 message_id 进行引用。

const targetApi = api.forProtocol('linux') // 或 'android'

萌卡 NT 通用消息发送接口，根据 message_type 路由到原生私聊或群聊发送链路。

调用

const result = await api.send_msg(self_id, message_type, target_id, message)

参数

底层协议参数也可以直接传 user_id 或 group_id。省略 message_type 时只能填写其中一项，框架会自动判定目标类型。

返回值

{ message_id: 123 }

示例

await api.send_msg(123456789, 'group', 778899, [
  { type: 'text', data: { text: '群消息' } },
])

const targetApi = api.forProtocol('linux') // 或 'android'

从 QQ 服务器读取指定群聊的历史消息。该接口使用 Android QQ 9.2.70 的 MessageSvc.PbGetGroupMsg，返回的 message_id 可以继续用于 get_msg、撤回、转发和标记已读。

调用示例

const result = await api.get_group_msg_history({
  self_id: 1060221,
  group_id: 123456789,
  message_seq: 0,
  count: 20,
  reverseOrder: false,
})

参数

v2.0.6 修复（v2.0.6）：message_seq=0 先读取服务器最新群消息序号，不依赖本地缓存，也不发送虚构的最大序号。返回的实际消息保存账号范围内的 message_id，可继续调用 get_msg；服务端已删除且没有发送者、时间的占位记录不作为消息返回。查询历史不会向插件重播消息事件。Android 双节点测试证据与 Linux 验收分开记录。

返回值

{
  "messages": [
    {
      "time": 1720000000,
      "self_id": 1060221,
      "post_type": "message",
      "message_type": "group",
      "message_id": 123456,
      "group_id": 123456789,
      "user_id": 106606,
      "message": [{ "type": "text", "data": { "text": "你好" } }],
      "raw_message": "你好"
    }
  ],
  "next_message_seq": 9980,
  "has_more": true
}

继续向前翻页时，把上一次返回的 next_message_seq 传给 message_seq。

该接口是只读查询。Android 使用上述 9.2.70 协议；Linux QQ 使用对应的原生历史消息能力，不会转发到同 QQ 的 Android 实例。

const targetApi = api.forProtocol('linux') // 或 'android'

从 QQ 服务器读取指定好友的一日漫游消息。该接口使用 Android QQ 9.2.70 的 MessageSvc.PbGetOneDayRoamMsg，返回结构与实时好友消息一致。

调用示例

const result = await api.get_friend_msg_history({
  self_id: 1060221,
  user_id: 106606,
  message_seq: 0,
  count: 20,
  reverseOrder: false,
})

参数

返回值

{
  "messages": [
    {
      "time": 1720000000,
      "self_id": 1060221,
      "post_type": "message",
      "message_type": "private",
      "message_id": 234567,
      "user_id": 106606,
      "target_id": 1060221,
      "message": [{ "type": "text", "data": { "text": "你好" } }],
      "raw_message": "你好"
    }
  ],
  "next_message_seq": 1719999000,
  "has_more": true
}

next_message_seq 在好友漫游协议中实际表示上一页最早消息的时间游标，调用方只需原样回传，不要自行换算。

该接口是只读查询。Android 使用上述 9.2.70 协议；Linux QQ 使用对应的原生历史消息能力，不会转发到同 QQ 的 Android 实例。

const targetApi = api.forProtocol('linux') // 或 'android'

将一条缓存消息的标准消息段重新发送给指定好友。

参数

await api.forward_friend_single_msg(1060221, message_id, 106606)

这是普通消息重发，不会生成 QQ 的合并转发卡片。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

将一条缓存消息的标准消息段重新发送到指定群聊。

参数

await api.forward_group_single_msg(1060221, message_id, group_id)

这是普通消息重发，不会生成 QQ 的合并转发卡片。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

上传好友聊天图片，并返回可直接传给 send_friend_msg 的图片消息段。

调用

const image = await api.upload_friend_image(
  self_id,
  user_id,
  file_path,
)

参数

返回值

{ type: 'image', data: { file_id: 'FILE_ID' } }

示例

const image = await api.upload_friend_image(
  3879548525,
  106030,
  'D:/Pictures/3840x2160.jpg',
)

await api.send_friend_msg(3879548525, 106030, [image])

const targetApi = api.forProtocol('linux') // 或 'android'

设置当前 QQ Bot 的头像。后端不发送媒体 OIDB 请求，图片会直接通过 Highway HTTP 上传。

调用

const result = await api.set_qq_avatar(self_id, file_path)

参数

图片大小上限为 5MB。建议使用 PNG 或 JPEG 图片。

返回值

{ success: true }

QQ头像 CDN 可能存在短暂缓存，上传成功后旧头像仍可能显示一段时间。

示例

await api.set_qq_avatar(
  123456789,
  'https://example.com/avatar.png',
)

const androidApi = api.forProtocol('android') // 省略时也默认 Android

上传群聊图片，并返回可直接发送的图片消息段。

调用

const image = await api.upload_group_image(
  self_id,
  group_id,
  file_path,
)

参数

返回值

{ type: 'image', data: { file_id: 'FILE_ID' } }

示例

const image = await api.upload_group_image(
  123456789,
  987654321,
  'D:/images/example.png',
)

await api.send_group_msg(123456789, 987654321, [image])

插件与萌卡NT不在同一台主机时，不要传插件主机的本地路径；应传后端可访问的 HTTP(S) 地址。

const targetApi = api.forProtocol('linux') // 或 'android'

上传群聊语音，并返回可直接发送的语音消息段。

调用

const voice = await api.upload_group_voice(self_id, group_id, file_path)

参数

后端通过 FFmpeg 解码常见音频格式，转换为单声道 24kHz PCM 后编码为 Silk，并生成语音波形。需要先安装并运行 FFmpeg 镜像。

返回值

{
  type: 'voice',
  data: {
    file_id: 'FILE_ID',
    duration: 5,
  },
}

返回段只能发送到上传时指定的群。

示例

const voice = await api.upload_group_voice(
  123456789,
  987654321,
  'D:/voices/example.mp3',
)

await api.send_group_msg(123456789, 987654321, [voice])

插件与萌卡NT不在同一台主机时，应传后端可访问的 HTTP(S) 地址。

const targetApi = api.forProtocol('linux') // 或 'android'

上传群聊 MP4 视频，并返回可直接发送的视频消息段。

调用

const video = await api.upload_group_video(self_id, group_id, file_path)

参数

后端通过已安装并运行的 FFmpeg 镜像读取视频尺寸与时长，并自动提取 PNG 封面。

返回值

{
  type: 'video',
  data: {
    file_id: 'FILE_ID',
  },
}

返回段可直接传给 send_group_msg，并应发送到上传时指定的群聊。视频必须作为唯一消息段单独发送。

示例

const video = await api.upload_group_video(
  123456789,
  987654321,
  'D:/videos/example.mp4',
)

await api.send_group_msg(123456789, 987654321, [video])

插件与萌卡NT不在同一台主机时，应传后端可访问的 HTTP(S) 地址。

const targetApi = api.forProtocol('linux') // 或 'android'

获取群聊合并转发消息的完整内容。

调用

const result = await api.get_group_forward_msg(
  self_id,
  sender_uin,
  res_id,
)

参数

返回值

{
  res_id: 'RESOURCE_ID',
  messages: [],
}

res_id 通常来自收到的合并转发卡片消息段。

const targetApi = api.forProtocol('linux') // 或 'android'

获取合并转发消息的节点内容，可使用 message_id 或简写字段 id。

传入框架消息事件中的 message_id 时，会自动使用消息缓存中的真实发送者和合并转发资源 ID；也可以直接传入 send_group_forward_msg 返回的 res_id。

const result = await api.get_forward_msg({
  self_id: 123456789,
  message_id: '合并转发消息的 message_id 或 res_id'
})

参数

返回值：

{
  "messages": [
    {
      "type": "node",
      "data": {
        "user_id": 123456789,
        "nickname": "发送者昵称",
        "content": [{ "type": "text", "data": { "text": "内容" } }],
        "time": 1787600000
      }
    }
  ]
}

const targetApi = api.forProtocol('linux') // 或 'android'

上传文本合并转发消息并返回可发送的合并转发消息段。

调用

const result = await api.send_group_forward_msg(
  self_id,
  group_id,
  messages,
)

参数

{
  type: 'node',
  data: {
    user_id: 123456789,
    nickname: '示例用户',
    time: 1710000000,
    content: [{ type: 'text', data: { text: '内容' } }],
  },
}

也兼容萌卡 NT 旧版扁平节点：

{
  user_id: 123456789,
  nickname: '示例用户',
  time: 1710000000,
  message: [{ type: 'text', data: { text: '内容' } }],
}

time 使用 Unix 秒。非 text 消息段会被忽略。

节点也可以填写 data.id，引用框架近 7 天消息缓存中的 message_id。对应消息必须仍在缓存且包含可转发的消息段。

返回值

{
  success: true,
  res_id: 'RESOURCE_ID',
  message: [{ type: 'ark', data: {} }],
  uploaded_messages: 1,
  discarded_messages: 0,
  discarded_segments: 0,
}

示例

const forward = await api.send_group_forward_msg(self_id, group_id, messages)
await api.send_group_msg(self_id, group_id, forward.message)

当前实现的该 action 只负责上传合并转发内容并生成消息段，不会直接发送；参数中不存在 upload_only。需要发送时，把返回的 message 交给 send_group_msg。

const targetApi = api.forProtocol('linux') // 或 'android'

生成指定好友的联系人分享 Ark。

调用

const result = await api.ArkSharePeer(self_id, user_id, phone_number)

参数

返回 { result, errMsg, arkMsg }，其中 arkMsg 可作为 Ark 消息内容继续发送。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

与 ArkSharePeer 使用同一套萌卡 NT 原生联系人分享链路，参数与返回值一致。

调用

const result = await api.send_ark_share(self_id, user_id, phone_number)

参数

详见 ArkSharePeer。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

生成指定群聊的分享 Ark。

调用

const ark = await api.ArkShareGroup(self_id, group_id)

参数

返回 Ark JSON 字符串。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

与 ArkShareGroup 使用同一套萌卡 NT 原生群聊分享链路，参数与返回值一致。

调用

const ark = await api.send_group_ark_share(self_id, group_id)

参数

详见 ArkShareGroup。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

向指定群聊发送 QQ 群红包，支持拼手气、普通、专属、语音和口令五种类型。

调用

const result = await api.send_group_red_packet(
  self_id,
  group_id,
  'lucky',
  100,
  2,
  payment_password,
  '恭喜发财',
)

total_amount 使用“分”为单位。上例表示总金额 1 元、共 2 份。

参数

红包类型对应关系：

原始 action 参数

{
  "action": "send_group_red_packet",
  "params": {
    "self_id": 123456789,
    "group_id": 987654321,
    "red_packet_type": "normal",
    "total_amount": 100,
    "total_num": 2,
    "wishing": "恭喜发财",
    "target_uins": [],
    "payment_password": "本次请求的支付密码"
  }
}

返回值

{
  status: 'success',
  red_packet_type: 'normal',
  group_id: 987654321,
  total_amount: 100,
  total_num: 2
}

支付密码不会写入框架配置。调用方也不应记录、缓存或输出该字段。建议先使用 dry_run: true 检查参数和路由，再执行正式发送。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

查询群消息中 red_packet 消息段对应的 QQ 红包详细信息。

调用

const redPacket = event.message.find(segment => segment.type === 'red_packet')
const result = await api.get_red_packet_info(
  event.self_id,
  event.group_id,
  event.sender.user_id,
  redPacket.data,
)

也可以直接把完整的 red_packet 消息段作为第 4 个参数传入，官方 SDK 会自动读取其中的 data。

参数

原始 action 参数

未使用官方 SDK 时，当前后端接收的是展开后的红包字段，不接收嵌套的 red_packet 对象：

{
  "action": "get_red_packet_info",
  "params": {
    "self_id": 644691423,
    "group_id": 714169244,
    "sender_uin": 51974055,
    "title": "恭喜发财",
    "listid": "10000448012608253500114336737900",
    "authkey": "45c7afde0cb06eed0198c763b46a580a",
    "channel": 1,
    "pay_flag": 0,
    "hb_from": 0
  }
}

请直接使用收到的红包消息段数据，不要自行重新生成 listid、authkey。官方 SDK 会自动把第 4 个位置参数展开成当前后端实际接收的字段。

返回值

返回 QQ 红包服务解密后的 JSON 对象，例如：

{
  retcode: '0',
  retmsg: 'ok',
  pre_grap_token: 'rand=...&sign=...&ts=...&ver=1',
  send_object: {
    channel: '1',
    recv_amount: '0',
    recv_num: '0',
    send_listid: '10000452012608021400100537757900',
    send_name: '示例用户',
    send_uin: '350873596',
    total_amount: '100',
    total_num: '1',
    wishing: '恭喜发财',
  },
  state: '16',
}

pre_grap_token 位于返回对象顶层。正式领取时，将它作为 grab_red_packet 的第 5 个参数传入。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

领取群消息中 red_packet 消息段对应的 QQ 红包。

调用

const redPacket = event.message.find(segment => segment.type === 'red_packet')
const info = await api.get_red_packet_info(
  event.self_id,
  event.group_id,
  event.sender.user_id,
  redPacket.data,
)
const result = await api.grab_red_packet(
  event.self_id,
  event.group_id,
  event.sender.user_id,
  redPacket.data,
  info.pre_grap_token,
)

也可以直接把完整的 red_packet 消息段作为第 4 个参数传入，官方 SDK 会自动读取其中的 data。

pre_grap_token 由 get_red_packet_info 返回，位于响应对象顶层。正式领取会将其作为 action 参数顶层的 pre_grap_token 发送。

Bot 的 skey、tenpay.com PsKey、昵称、设备指纹、协议 AppID 和红包加密上下文均由后端自动获取。

参数

原始 action 参数

未使用官方 SDK 时，当前后端接收展开后的红包字段，pre_grap_token 同样放在 params 顶层：

{
  "action": "grab_red_packet",
  "params": {
    "self_id": 644691423,
    "group_id": 714169244,
    "sender_uin": 51974055,
    "title": "恭喜发财",
    "listid": "10000448012608253500114336737900",
    "authkey": "45c7afde0cb06eed0198c763b46a580a",
    "channel": 1,
    "pay_flag": 0,
    "hb_from": 0,
    "pre_grap_token": "get_red_packet_info 返回的 pre_grap_token"
  }
}

请直接使用收到的红包消息段数据，不要自行重新生成 listid、authkey。官方 SDK 会自动把第 4 个位置参数展开成当前后端实际接收的字段。

返回值

返回 QQ 红包服务解密后的领取结果 JSON 对象。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

获取指定群聊中当前仍可领取的红包。

调用

const packets = await api.get_group_red_packets(self_id, group_id)

参数

返回值

返回红包数组。没有可领取红包时返回空数组。

[
  {
    sender_uin: 123456789,
    title: '恭喜发财',
    listid: '红包列表 ID',
    authkey: '领取凭据',
    channel: 1,
    pay_flag: 0,
    hb_from: 0,
    time: 1710000000,
  },
]

const androidApi = api.forProtocol('android') // 省略时也默认 Android

获取指定群聊中当前仍可领取的红包，与 get_group_red_packets 返回相同结果。

调用

const packets = await api.get_up_for_grabs(self_id, group_id)

参数

返回值

返回红包数组。没有可领取红包时返回空数组。字段与 get_group_red_packets 相同。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

读取框架当前进程已观察到的 OneBot 消息数据，不请求 QQ 历史消息。

参数

返回 message_type、message_id、message_seq、发送者、标准消息段、原始文本，以及群消息可用的 group_id。

缓存按账号严格隔离，保留 7 天且每账号最多 4096 条；它是进程内缓存，框架重启后不会保留。不存在、已过期或重启前的消息会直接返回缓存未命中，不会自动拉取 QQ 历史记录。

const targetApi = api.forProtocol('linux') // 或 'android'

• action：get_flash_image
• 最低版本：框架与 Node.js SDK v2.2.1。

读取当前账号实时收到的闪照原图地址及图片信息。当前识别 CommonElem service 3 的群聊和私聊闪照。私聊消息未携带 origUrl 时，使用 QQ 明确提供的 downloadPath 按私聊原图路由解析；不会只凭 resId、文件名或 MD5 构造地址。私聊已使用 Android 与 Linux QQ 接收真实闪照验证，接口返回地址可下载且大小、MD5 一致；群聊原图地址路径尚未实测。

const image = await api.forProtocol('android').get_flash_image(selfId, messageId)
// image.url 为 QQ 消息提供的原图地址；能否访问以 QQ 服务端为准。

参数

返回

{
  "message_id": 123456,
  "index": 0,
  "count": 1,
  "file_id": "upstream-file-id",
  "url": "https://gchat.qpic.cn/upstream-original-path",
  "name": "upstream-file-name",
  "md5": "",
  "size": 512,
  "width": 120,
  "height": 80
}

size 单位为字节。上游未提供的数值为 0、文本为空字符串；URL 缺失会报错。示例地址为占位，不能直接访问。

框架返回消息明确提供的原图地址，或由 QQ 提供的私聊 downloadPath 按原图路由解析的地址，不自动下载、不保存图片、不报告已查看、不修改 QQ 的有效期。成功返回表示找到地址，不代表已验证图片仍可访问；QQ 拒绝访问时不能用此接口恢复。收到消息、调试参数预览都不会触发图片请求。

消息识别与缓存

群聊和私聊消息中的闪照使用独立的 flash_image 段：

{ "type": "flash_image", "data": { "file_id": "upstream-file-id", "width": 120, "height": 80 } }

将外层消息事件的 message_id 交给本接口。消息段不自动携带 URL，普通 image 不会被当作闪照。不从历史查询补缓存，不查询其他账号或其他协议的消息。元数据仅存内存，最多保留 2 分钟、256 条消息；重复投递不延长已有缓存，重登或框架重启后失效。这个期限是本地元数据保留上限，不是 QQ 闪照的有效期承诺。

错误

• flash_image_unavailable：当前账号协议没有收到此闪照、元数据已过期或登录会话变更。
• flash_image_url_unavailable：消息没有提供可用原图地址或受支持的私聊下载路径；不会根据 MD5、文件 ID 或缩略图猜测原图地址。
• flash_image_index_out_of_range：下标超出此消息的闪照数量。
• 参数、服务 Token 和账号权限检查失败时按现有 action 错误契约返回。

协议字段参考：MiraiGo 消息结构。这仅证明结构定义，不代表 QQ 当前所有客户端均返回可下载地址。

根据 QQ Android 9.2.70 实际接收的音乐分享结构，生成可由 send_msg、send_group_msg 或 send_friend_msg 发送的 Ark 音乐卡片。

调用方提供歌曲名称、歌手、跳转地址、封面和音频地址；框架向音乐卡片签名服务提交这些公开展示字段，并校验返回值确实包含 view=music 和内容绑定 token。框架不会向签名服务发送 QQ 登录凭据、插件令牌或群聊信息。

调用

const { data: musicArk } = await api.get_music_ark(self_id, {
  type: 'qq',
  title: '一半',
  content: '柯基林',
  url: 'https://i.y.qq.com/v8/playsong.html?songid=718815077',
  audio: 'https://example.com/audio/one-half.mp3',
  image: 'https://example.com/image/one-half.jpg',
})

await api.send_group_msg(self_id, group_id, [
  { type: 'ark', data: musicArk },
])

参数

qq 和 163 都生成 view=music 可播放卡片，并自动填写对应的来源名称、应用 ID 与图标。

返回值

{
  "data": {
    "app": "com.tencent.music.lua",
    "config": {},
    "extra": {},
    "meta": {},
    "prompt": "[分享]一半",
    "ver": "0.0.0.1",
    "view": "music"
  }
}

将 data 原样放入 { "type": "ark", "data": ... } 消息段。不要把整个返回对象作为消息段的 data。

错误说明

• self_id 必须对应当前调用连接可用的在线账号。
• 所有 URL 必须是带主机名的完整 http:// 或 https:// 地址。
• 缺少 audio 时会在生成阶段直接报错，不会产生无法播放的卡片。
• 签名服务不可用、返回非 JSON、非音乐卡片或缺少 token 时，接口会返回明确错误。
• self_id 只用于选择调用账号和执行插件权限校验，不会被发送给外部签名服务。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

分页获取群消息指定表情的回应用户。

调用

const page = await api.fetch_emoji_like({
  self_id: 106606,
  message_id: 123456789,
  emoji_id: '76',
  count: 100,
  cookie: '',
  emoji_type: 0,
})

返回 emojiLikesList、下一页 cookie、isFirstPage 和 isLastPage。继续翻页时原样传入上次返回的 cookie。

该接口只读取回应用户，不会添加或取消表情回应。当前仅支持 Android QQ。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

自动翻页获取群消息指定表情的全部回应用户。

调用

const result = await api.get_emoji_likes({
  self_id: 106606,
  message_id: 123456789,
  emoji_id: '76',
  emoji_type: 0,
})

返回 { emoji_like_list }，每项包含 user_id 和 nick_name。

框架最多自动读取 10 页，并在服务端返回末页、空游标或重复游标时立即停止。该接口不会添加或取消表情回应。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

按 user_id 向好友发送消息。该 action 已作为萌卡 NT 正式 API 注册，并复用 send_friend_msg 的原生发送链路。

调用

const result = await api.forProtocol('android').send_private_msg({ self_id, user_id, message })

参数

返回值

成功返回 { message_id: number }，可用于查询、回复或撤回；该接口不返回 success、msg_seq 或 msg_random，不要套用 send_friend_msg 的返回结构。调用失败通过 action 错误返回。非好友群临时会话请使用独立的 send_group_temp_msg，不要把群成员 QQ 号直接当作好友调用。

const targetApi = api.forProtocol('linux') // 或 'android'

通过共同群聊向群成员发送 QQ 原生临时会话消息。目标 QQ 不需要与发送账号建立好友关系。

调用

const result = await api.send_group_temp_msg(self_id, group_id, user_id, message)

参数

框架会在发送前从 QQ 服务器读取群成员列表，确认发送账号和目标 QQ 都在该群中。group_id 会写入 Android QQ 的临时会话协议路由，不会降级成普通好友私聊。

如果群设置禁止普通成员发起临时会话，普通成员调用会直接返回权限错误；群主和管理员仍可正常发送。

返回值

{
  success: true,
  message_id: 123456789,
  msg_seq: 123,
  msg_random: 456,
  message_type: 'private',
  sub_type: 'group',
  group_id: 987654321
}

示例

await api.send_group_temp_msg(123456789, 987654321, 112233445, [
  { type: 'text', data: { text: '你好，我从群成员列表联系你。' } },
])

收到的临时会话事件仍属于私聊消息，但会额外携带 sub_type: 'group' 和来源 group_id。

引用回复

临时会话支持 QQ 原生引用回复。被引用消息必须来自同一来源群与同一目标成员：

await api.send_group_temp_msg(self_id, group_id, user_id, [
  { type: 'reply', data: { message_id: event.message_id } },
  { type: 'text', data: { text: '收到。' } },
])

该能力只通过萌卡原生 send_group_temp_msg 开放，不注册 OneBot 私聊兼容入口。

const targetApi = api.forProtocol('linux') // 或 'android'

撤回一条框架近期收到或发送的消息。框架根据 message_id 自动选择群聊或私聊的安卓协议撤回链路。

参数

await api.delete_msg(1060221, message_id)

消息引用默认保留 7 天；引用过期、目标消息已不可撤回或服务端拒绝时会返回明确错误。

const targetApi = api.forProtocol('linux') // 或 'android'

把指定群消息标记为已读。框架从 message_id 解析真实群号和消息序号，再通过安卓协议上报已读游标。

await api.mark_group_msg_as_read(1060221, message_id)

const targetApi = api.forProtocol('linux') // 或 'android'

把指定好友消息标记为已读。框架从 message_id 解析对端 QQ 和消息时间，再通过安卓协议上报已读游标。

await api.mark_private_msg_as_read(1060221, message_id)

const targetApi = api.forProtocol('linux') // 或 'android'

标记一条消息已读。框架根据消息引用自动选择群聊序号或私聊时间游标。

await api.mark_msg_as_read(1060221, message_id)

const targetApi = api.forProtocol('linux') // 或 'android'

设置指定群聊的头像。萌卡NT会按 QQ Android 9.2.70 的 Highway command_id=3000 上传链路，先获取当前账号的 Highway 会话，再将公开群号转换为 QQ 内部群 UIN 后提交图片。

调用

const result = await api.set_group_portrait(self_id, group_id, file)

参数

图片必须是有效的 GIF、JPEG 或 PNG，大小不超过 10 MiB。调用账号必须是群主或具备修改群头像的管理员权限。

返回值

{
  result: 0,
  errMsg: '',
  new_seq: 24,
}

result 为 0 表示 QQ 已接受上传；非零值会作为调用错误返回。权限不足时 QQ 会返回 No Perm，不会被框架伪装为上传成功。群头像 CDN 可能有短暂缓存。

示例

await api.set_group_portrait(
  1060221,
  106500,
  'https://example.com/group-avatar.png',
)

const androidApi = api.forProtocol('android') // 省略时也默认 Android

将本地文件或可下载的 HTTP(S) 文件发送给指定 QQ 好友。框架使用 QQ Android 9.2.70 的离线文件通道，依次完成签名申请、Highway 上传和私聊文件消息下发。

const result = await api.upload_private_file({
  self_id: 2082083,
  user_id: 1060221,
  file: 'D:/Mengka-NT/files/report.txt',
  name: 'report.txt',
})

成功时返回：

{
  "success": true,
  "file_id": "文件 UUID",
  "file_name": "report.txt",
  "file_size": 128,
  "message_id": 4399468640647658,
  "msg_seq": 7117,
  "client_seq": 10321
}

file_id 会缓存文件校验信息，可继续交给 get_private_file_url 获取下载地址；message_id 使用框架统一消息引用，可用于消息查询等后续操作。

const targetApi = api.forProtocol('linux') // 或 'android'

萌卡 NT 通用合并转发接口。填写 user_id 时发送给好友，填写 group_id 时发送到群聊；两个目标参数必须且只能填写一个。

私聊示例

const result = await api.send_forward_msg({
  self_id,
  user_id: 123456789,
  messages: [{
    type: 'node',
    data: {
      user_id: 123456789,
      nickname: '示例用户',
      content: '这是一条合并转发内容',
    },
  }],
})

群聊示例

const result = await api.send_forward_msg({
  self_id,
  group_id: 123456789,
  messages,
})

节点结构、消息引用、返回字段与 send_private_forward_msg 和 send_group_forward_msg 一致。

const targetApi = api.forProtocol('linux') // 或 'android'

创建文本合并转发消息并发送给指定好友，使用当前账号的原生发送链路。

调用

const result = await api.forProtocol('android').send_private_forward_msg({
  self_id,
  user_id,
  messages,
})

参数

标准节点示例：

{
  type: 'node',
  data: {
    user_id: 123456789,
    nickname: '示例用户',
    time: 1710000000,
    content: [{ type: 'text', data: { text: '内容' } }],
  },
}

content 也可以直接填写字符串。节点使用 data.id 时，会引用框架 近期缓存的 message_id。当前版本生成合并转发正文时支持 text 消息段，其余消息段会计入返回值中的 discarded_segments。

返回值

{
  success: true,
  message_id: 'MESSAGE_REFERENCE',
  res_id: 'RESOURCE_ID',
  forward_id: 'RESOURCE_ID',
  uploaded_messages: 1,
  discarded_messages: 0,
  discarded_segments: 0,
}

const targetApi = api.forProtocol('linux') // 或 'android'

根据内置模板或完整小程序参数生成可发送的 Ark 数据。

调用

const result = await api.get_mini_app_ark(self_id, {
  type: 'bili',
  title: '视频标题',
  desc: '视频简介',
  jumpUrl: 'https://www.bilibili.com/video/BV...',
})

主要参数

不使用内置模板时，可额外传 appId、sdkId、iconUrl、versionId、scene、templateType、businessType、verType 和 shareType。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

获取指定群聊当前可用的 AI 声音角色。

调用

const categories = await api.get_ai_characters(self_id, group_id, 1)

返回分类数组；每个分类包含可用于合成的角色 ID 和展示名称。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

使用指定 AI 声音角色合成语音并返回访问地址。

调用

const url = await api.get_ai_record(self_id, group_id, character, text, 1)

合成可能需要数秒，成功返回临时语音 URL。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

合成并直接向指定群聊发送 AI 语音。

调用

await api.send_group_ai_record(self_id, group_id, character, text, 1)

参数

参数规则与 get_ai_record 相同。成功表示 QQ 已接受发送流程，返回 { message_id: 0 }。

const androidApi = api.forProtocol('android') // 省略时也默认 Android

识别框架近期收到并缓存的群语音文字。

调用

const result = await api.fetch_ptt_text(self_id, message_id, 0)

成功返回 { text }。消息引用或语音元数据过期后无法再次识别。

const androidApi = api.forProtocol('android') // 省略时也默认 Android