API 总览

获取当前在线 Bot 的登录号信息，返回结构与 OneBot/NapCat 同名接口一致。

调用

const info = await api.get_login_info(self_id)

参数

返回值

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

接口不会返回密码、登录票据或其他敏感身份信息。

获取当前在线 Bot 的连接状态与基础运行计数，返回结构与 OneBot/NapCat 同名接口兼容。

调用

const status = await api.get_status(self_id)

参数

返回值

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

online 只有在账号状态为在线且 MSF 连接处于已连接状态时才为 true。

获取萌卡 NT 框架版本和兼容协议版本。

调用

const version = await api.get_version_info(self_id)

参数

返回值

{
  app_name: 'Mengka-NT',
  protocol_version: 'v11',
  app_version: '1.5.11',
}

app_version 使用当前运行二进制的框架版本，不写死在 SDK 中。

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

const clients = await api.get_online_clients({
  self_id: 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 优先使用服务端平台名称。账号刚登录且设备推送尚未到达时会返回空数组，收到推送后会自动更新。

获取当前 QQ 账号与设备型号可用的在线机型显示名称。接口由萌卡 NT 后端直接使用当前账号的 Android 9.2.70 登录态、设备指纹和 QQ 会员机型服务完成，不依赖 NapCat 或其他框架进程。

const result = await api._get_model_show({
  self_id: 1060221,
  model: 'Xiaomi 14 Pro',
})

成功时返回：

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

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

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

await api._set_model_show({
  self_id: 1060221,
  model: 'Xiaomi 14 Pro',
  model_show: 'Xiaomi 14 Pro',
})

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

设置当前在线 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)

设置当前在线 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)

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

调用

await api.set_input_status(self_id, user_id, event_type)

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

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

调用

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

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

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

调用

const result = await api.can_send_image(self_id)

参数

返回值

{ yes: true }

只有通过在线状态和节点归属校验的 Bot 才能调用该接口。

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

调用

const result = await api.can_send_record(self_id)

参数

返回值

{ yes: true }

只有通过在线状态和节点归属校验的 Bot 才能调用该接口。

将公开 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 文件。

以分片帧下载文件。多账号框架在解析 QQ 媒体 file_id 时应传 self_id；公开 URL、Base64 或框架目录内文件可省略。

await api.download_file_stream({ self_id: 123456789, file_id: 'file-id', chunk_size: 65536 })

框架先发送 action_stream：第一帧 data_type=file_info，随后为一个或多个 file_chunk；最终 action_result.data.data_type=file_complete。chunk_size 范围为 1 字节到 4 MiB，文件总大小上限为 128 MiB。

参数及分片顺序与 download_file_stream 相同。首个 file_info 额外返回 width、height，无法识别为图片时请求失败。

await api.download_file_image_stream({ self_id: 123456789, file_id: 'image-id' })

流式下载语音。可选 out_format：mp3、amr、wma、m4a、spx、ogg、wav、flac；转换依赖框架管理的 FFmpeg 容器。

await api.download_file_record_stream({ self_id: 123456789, file_id: 'voice-id', out_format: 'mp3' })

按 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 个测试帧发送完毕后返回失败响应。

重启当前萌卡 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"]
  }
}

使用当前 QQ 9.2.70 登录会话发送已组装的原生协议包。

调用

const responseHex = await api.send_packet(self_id, cmd, data, true, reserve)

等待回包时返回小写十六进制字符串；rsp=false 时成功返回 null。

发送群聊消息。

调用

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 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 进行引用。send_private_msg 和 send_msg 使用同一种 reply 消息段。

通过共同群聊向群成员发送 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: '收到。' } },
])

OneBot 兼容接口 send_private_msg 在同时传入 group_id 和 user_id 时，会自动使用此临时会话能力。

OneBot 兼容的私聊发送接口。默认使用好友消息链路；同时传入来源 group_id 时使用 QQ 原生群临时会话链路。

调用

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

参数

返回值

{ message_id: 123 }

message_id 对应 QQ 回执中的消息序号。错误会通过标准 action_result 返回。

示例

await api.send_private_msg(123456789, 112233445, '你好 🎉')

向非好友群成员发送临时会话：

socket.send(JSON.stringify({
  type: 'action',
  action: 'send_private_msg',
  id: 'temp-1',
  params: {
    self_id: 123456789,
    group_id: 987654321,
    user_id: 112233445,
    message: '你好，我从群成员列表联系你。',
  },
}))

user_id 必须使用 QQ 号，不接受 UID。临时会话发送前会校验双方都在 group_id 指定的群内。

OneBot/NapCat 兼容的通用消息发送接口，根据 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: '群消息' } },
])

对 OneBot 消息事件或请求事件执行一组快速操作。该接口主要用于兼容反向 HTTP 上报的快速响应；WebSocket 插件也可直接调用。

await api.call('.handle_quick_operation', {
  context,
  operation
})

参数

消息事件支持：

请求事件支持：

示例

收到群消息后回复、@发送者并禁言 10 分钟：

await api.call('.handle_quick_operation', {
  context: event,
  operation: {
    reply: '已收到',
    at_sender: true,
    ban: true,
    ban_duration: 600
  }
})

说明

• 操作按照回复、撤回、踢出、禁言的顺序执行；任一步失败会返回明确的 action 名称和错误原因。
• 匿名群消息不执行 at_sender、kick 或 ban。
• 该接口复用 send_group_msg、send_private_msg、delete_msg、set_group_kick、set_group_ban、set_friend_add_request 和 set_group_add_request 的现有实现。

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

参数

await api.delete_msg(1060221, message_id)

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

读取框架消息引用中保留的 OneBot 消息数据。

参数

返回 message_type、message_id、message_seq、发送者、标准消息段、原始文本和可用的 group_id。该接口读取框架缓存，不会重新拉取已过期的 QQ 历史消息。

从 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,
})

参数

返回值

{
  "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。

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

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

await api.forward_friend_single_msg(1060221, message_id, 106606)

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

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

await api.forward_group_single_msg(1060221, message_id, group_id)

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

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

await api.mark_group_msg_as_read(1060221, message_id)

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

await api.mark_private_msg_as_read(1060221, message_id)

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

await api.mark_msg_as_read(1060221, message_id)

将框架近期缓存中的所有会话标记为已读。框架会合并内存与 Redis 消息引用，只为每个群聊和每个好友上报最新游标。

await api._mark_all_as_read(1060221)

该接口只处理框架已收到并保留引用的消息，不会假装清除 QQ 服务端上从未同步到框架的历史未读会话。

上传好友聊天图片，并返回可直接传给 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])

设置当前 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',
)

设置指定群聊的头像。萌卡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(
  106500,
  'https://example.com/group-avatar.png',
  1060221,
)

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

调用

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 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) 地址。

上传群聊 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) 地址。

将本地文件或可下载的 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 result = await api.get_group_forward_msg(
  self_id,
  sender_uin,
  res_id,
)

参数

返回值

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

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

获取合并转发消息的节点内容，兼容 Go-CQHTTP 与 NapCat 的 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
      }
    }
  ]
}

NapCat 通用合并转发接口。填写 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 一致。

创建文本合并转发消息并发送给指定好友，参数与 NapCat/Go-CQHTTP 兼容。

调用

const result = await api.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,
}

上传文本合并转发消息并直接发送到目标群，行为与 NapCat/Go-CQHTTP 一致。

调用

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

参数

NapCat 标准节点结构：

{
  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,
  message_id: 'MESSAGE_REFERENCE',
  res_id: 'RESOURCE_ID',
  forward_id: 'RESOURCE_ID',
  message: [],
  uploaded_messages: 1,
  discarded_messages: 0,
  discarded_segments: 0,
}

示例

const forward = await api.send_group_forward_msg(self_id, group_id, messages)
console.log(forward.message_id, forward.res_id)

向指定群聊发送 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 检查参数和路由，再执行正式发送。

查询群消息中 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 必须作为对象放在 params 内：

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

请直接使用收到的红包消息段数据，不要自行拆分或重新生成 listid、authkey。官方 SDK 会兼容尚未更新的框架版本。

返回值

返回 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 个参数传入。

领取群消息中 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 时，red_packet 必须作为对象放在 params 内，pre_grap_token 放在 params 顶层：

{
  "action": "grab_red_packet",
  "params": {
    "self_id": 644691423,
    "group_id": 714169244,
    "sender_uin": 51974055,
    "red_packet": {
      "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 会兼容尚未更新的框架版本。

返回值

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

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

调用

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,
  },
]

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

调用

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

参数

返回值

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

根据内置模板或完整小程序参数生成可发送的 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。

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

调用

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

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

生成指定群聊的分享 Ark。

调用

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

返回 Ark JSON 字符串。

ArkSharePeer 的兼容调用名，参数与返回值一致。

调用

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

详见 ArkSharePeer。

ArkShareGroup 的兼容调用名，参数与返回值一致。

调用

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

详见 ArkShareGroup。

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

调用

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

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

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

调用

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

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

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

调用

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

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

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

调用

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

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

为群消息添加或取消指定表情回应。

调用

await api.set_msg_emoji_like(self_id, message_id, emoji_id, true)

仅支持群消息。

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

调用

const page = await api.fetch_emoji_like(self_id, message_id, emoji_id, 100, cookie, 0)

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

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

调用

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

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

获取 Bot 的完整好友列表。萌卡NT会自动完成分页。

调用

const result = await api.get_friend_list(self_id)

参数

返回值

{
  friends: [],
  total_count: 0,
  self_uin: 123456789,
}

获取当前账号的单向好友列表。单向好友是仍关注当前账号、但没有出现在普通双向好友列表中的用户。

const users = await api.get_unidirectional_friend_list({
  self_id: 106606,
  top: 0,
  count: 99,
})

成功时直接返回用户数组：

[
  {
    "uin": 1122334455,
    "uid": "u_example",
    "nick_name": "示例用户",
    "age": 0,
    "source": "通过群聊"
  }
]

nick_name 和 source 由框架解码 QQ Android 9.2.70 的真实响应得到，不使用好友缓存拼接。没有单向好友时返回空数组。

获取当前登录 QQ 的资料获赞记录。接口使用 QQ Android 9.2.70 的真实 VisitorSvc.ReqGetVoterList 请求，不读取网页缓存。

const result = await api.get_profile_like({
  self_id: 2082083,
  user_id: 2082083,
  start: 0,
  count: 10,
})

成功时返回：

{
  "uid": "u_example",
  "time": "1787612400",
  "favoriteInfo": {
    "userInfos": [],
    "total_count": 0,
    "last_time": 0,
    "today_count": 0
  },
  "voteInfo": {
    "userInfos": [
      {
        "uin": 1122334455,
        "uid": "u_example_friend",
        "nick": "示例用户",
        "count": 1,
        "latestTime": 1787612300,
        "isFriend": true
      }
    ],
    "total_count": 100,
    "new_count": 2,
    "new_nearby_count": 0,
    "last_visit_time": 1787612400
  }
}

voteInfo.userInfos 是分页获赞用户；total_count 是累计获赞数，new_count 是当天获赞数。uid 和 isFriend 会在好友资料可用时补齐；非好友不会通过猜测生成 UID。

QQ 9.2.70 的此响应没有稳定提供 VIP/SVIP 标志，因此兼容字段 isvip、isSvip 当前返回 false。

获取当前 QQ 最近会话。QQ Android 9.2.70 的最近会话来自客户端本地消息数据库，框架对应返回自己已接收或发送、并写入持久化消息引用的私聊与群聊会话。

调用

await api.get_recent_contact(self_id, count)

参数

返回值

按最后消息时间从新到旧返回，私聊和群聊分别去重：

[
  {
    "peerUin": "106500",
    "peerName": "测试群",
    "msgTime": "1787620800",
    "msgId": "123456789",
    "lastestMsg": {
      "message_type": "group",
      "group_id": 106500,
      "message": [{ "type": "text", "data": { "text": "测试" }],
      "raw_message": "测试"
    }
  }
]

lastestMsg 保持 NapCat 的字段拼写以兼容现有插件。框架只返回自身七天消息引用缓存中已观察到的会话，不会读取手机 QQ 的私有本地数据库。

设置或清除指定好友的备注。该接口使用 QQ Android 9.2.70 的好友备注协议，并在发送前把 QQ 号解析为真实 QQNT UID。

调用

await api.set_friend_remark(self_id, user_id, remark)

参数

返回值

成功时返回空数据：

null

如果目标不是当前账号的好友，或无法解析其 QQNT UID，接口会直接返回可读错误，不会把数字 QQ 号伪装成 UID 发送。

处理好友申请。框架会先向 QQ Android 9.2.70 查询当前好友系统消息，再用 flag 匹配真实申请并复用其中的来源字段发送同意或拒绝操作。

调用

await api.set_friend_add_request(
  1060221,
  event.flag,
  true,
  '新朋友'
)

参数

返回

成功时返回空数据；申请已处理、flag 过期或不存在时返回明确错误。

获取 QQ 标记为可疑的待处理好友申请。

调用

const requests = await api.get_doubt_friends_add_request(self_id, count)

每项包含 flag、uin、nick、source、reason 和 time。后续处理必须原样使用 flag。

同意一条可疑好友申请。

调用

await api.set_doubt_friends_add_request(self_id, flag, true)

成功返回 null。

删除指定好友。

调用

const result = await api.delete_friend(self_id, target_uin)

参数

返回值

{ success: true, target_uin: 112233445 }

获取好友空间首包中的最新动态。

调用

const result = await api.get_qzone_friend_feeds(self_id)

参数

返回值

{
  self_id: 123456789,
  feeds: [],
  total_count: 0,
}

动态常用字段：

完整 feed 可直接传给点赞与取消点赞 API。

执行前会强制查询当前 QQ 等级；等级低于 16 级时请求会被拒绝。

发布一条文本 QQ 空间动态。

调用

const result = await api.publish_qzone_feed(
  self_id,
  content,
  visibility,
  self_delete_after_one_day,
  declare_ai_generated,
)

参数

返回值

{
  self_id: 123456789,
  feed: {},
  client_feed_id: 'CLIENT_FEED_ID',
  server_time: 1710000000,
}

返回的 feed 可用于 comment_qzone_feed、like_qzone_feed 或 unlike_qzone_feed。

发布可带图片、可见范围和指定好友范围的空间动态。

调用

const result = await api.send_qzone_msg(
  self_id,
  '动态正文',
  ['https://example.com/image.jpg'],
  1,
  [],
)

成功返回 { tid }，可用于后续删除。

删除当前账号发布的空间动态。

调用

await api.delete_qzone_msg(self_id, tid)

成功返回 null。删除结果以再次查询空间动态为准。

评论一条好友 QQ 空间动态，支持纯文字、纯图片及图文同时发送。

调用

const result = await api.comment_qzone_feed(self_id, feed, content, images)

参数

content 与 images 至少填写一项。动态内部所需的标识由框架根据 feed 自动处理。

返回值

{
  self_id: 123456789,
  comment_id: 'COMMENT_ID',
  content: '评论内容',
  images: [
    { url: 'https://example.com/image.jpg', width: 1080, height: 1080 },
  ],
  created_at: 1710000000,
}

示例

const { feeds } = await api.get_qzone_friend_feeds(self_id)

// 纯文字
await api.comment_qzone_feed(self_id, feeds[0], '写得真不错', [])

// 纯图片
await api.comment_qzone_feed(self_id, feeds[0], '', [
  'https://example.com/comment.jpg',
])

// 图文同时发送
const result = await api.comment_qzone_feed(self_id, feeds[0], '配图评论', [
  { url: 'https://example.com/comment.jpg', width: 1080, height: 1080 },
])
console.log(result.comment_id, result.images)

框架会下载图片并自动上传到当前账号的 QQ 空间媒体存储，再提交评论。图片地址必须能由框架服务器通过公网访问；不支持内网地址。本地文件需先放到可访问的 HTTP(S) 地址。

执行前会强制查询当前 QQ 等级；等级低于 16 级时请求会被拒绝。

点赞一条好友空间动态。

调用

api.like_qzone_feed(self_id, feed)

参数

返回值

此 API 不等待响应，不返回 Promise。

const { feeds } = await api.get_qzone_friend_feeds(self_id)
api.like_qzone_feed(self_id, feeds[0])

转发动态会根据 feed.forward 自动处理。

取消对好友空间动态的点赞。

调用

api.unlike_qzone_feed(self_id, feed)

参数

返回值

此 API 不等待响应，不返回 Promise。

const { feeds } = await api.get_qzone_friend_feeds(self_id)
api.unlike_qzone_feed(self_id, feeds[0])

获取 QQ 名片信息。

调用

查询当前 Bot：

const result = await api.get_summary_card(self_id)

查询指定用户：

const result = await api.get_summary_card(self_id, target_uin)

参数

返回值

返回目标用户的名片结构化数据。

设置当前 QQ Bot 的昵称、性别和个性签名。昵称与性别使用 QQ Android 9.2.70 的资料编辑协议；个性签名使用内容审核与富签名保存链路，并支持重复提交同一个值。

调用

const result = await api.set_qq_profile(self_id, nickname, personal_note, sex)

参数

返回值

{
  success: true,
  summary_card: {
    nickname: '新的昵称',
    sign: '新的个性签名'
  }
}

框架在写入后重新读取 QQ 名片。QQ 当前把个性签名放在 richSign 中时，框架会自动解析并同步到标准 sign 字段。重复提交相同签名会直接返回成功，不会把 QQ 审核服务的重复内容回执误报为失败。

示例

await api.set_qq_profile(123456789, '萌卡机器人', '今天也要开心', 1)

设置或清空当前 QQ Bot 的个性签名。实现严格复用 QQ Android 9.2.70 的真实链路：先通过 Signature.auth 审核内容，再把服务端返回的 key 和审核后签名内容写入 ProfileService.SetRichSig。清空签名使用客户端独立的 OidbSvc.0x510_0 请求。

调用

const result = await api.set_self_longnick(self_id, longNick)

参数

兼容参数名 long_nick，但新插件建议统一使用 longNick。

返回值

{
  success: true,
  summary_card: {
    sign: '新的个性签名'
  }
}

保存成功后框架会读取一次最新 QQ 名片。若 QQ 名片服务短暂延迟，接口仍返回 success: true，并在 readback_warning 中说明读取失败原因；可稍后调用 get_summary_card 再确认。

示例

// 设置签名
await api.set_self_longnick(123456789, '今天也要开心')

// 清空签名
await api.set_self_longnick(123456789, '')

点赞指定用户的 QQ 名片。

调用

const result = await api.like_summary_card(
  self_id,
  target_uin,
  like_count,
)

参数

返回值

{ code: 0, msg: '成功' }

code 和 msg 来自 QQ 名片点赞响应。

获取当前 Bot 会话的 skey。

调用

const result = await api.get_skey(self_id)

参数

返回值

{ skey: 'SKEY' }

该凭据属于当前 Bot 会话，应仅在插件运行期间使用。

获取当前 Bot 协议和设备指纹对应的 QQ Android WebView User-Agent。

调用

const result = await api.get_user_agent(self_id)

参数

返回值

{
  user_agent: 'Mozilla/5.0 ...'
}

返回值根据 Bot 当前绑定的协议版本和设备指纹生成。

获取当前 Bot 会话的 clientkey。

调用

const result = await api.get_clientkey(self_id)

参数

返回值

{ clientkey: 'HEX_ENCODED_CLIENTKEY' }

clientkey 使用十六进制编码。

获取指定域名的 PsKey。

调用

const result = await api.get_pskey(self_id, domain)

参数

返回值

{
  domain: 'DOMAIN',
  pskey: 'PSKEY',
}

获取当前账号用于私聊、群聊和媒体资源访问的 RKey。

调用

const keys = await api.get_rkey(self_id)

参数

返回值

返回数组；每项包含 type、type_id、rkey、created_at、ttl 和 expired。RKey 属于敏感临时凭证，不应写入日志或长期保存。

get_rkey 的兼容调用名，参数和返回值完全一致。

调用

const keys = await api.nc_get_rkey(self_id)

详见 get_rkey。

以服务信息结构返回私聊和群聊媒体 RKey。

调用

const server = await api.get_rkey_server(self_id)

返回值

{
  name: 'Mengka NT',
  private_rkey: '...',
  group_rkey: '...',
  expired_time: 1770000000,
}

expired_time 为两类 RKey 中较早的过期时间。

使用当前在线的安卓协议 Bot 创建普通 QQ 群。底层按 QQ 9.2.70 的创建群链路执行：先创建群聊，再按需邀请成员。

调用

const result = await api.create_group({
  self_id: 1060221,
  group_name: '萌卡 NT API 验证群',
  description: '用于验证安卓协议群聊接口',
  user_ids: [106606],
  invite_message: 'API 联调邀请',
})

参数

返回值

没有填写邀请成员时：

{
  created: true,
  group_id: 987654321,
  group_uin: 1234567890,
  owner_id: 1060221,
  group_size: 1,
  group_name: '萌卡 NT API 验证群',
  invite_attempted: false,
  invite_success: false,
}

填写邀请成员时，返回值会额外包含 invite_user_ids 和 invite。创建群聊和邀请成员是两个独立阶段；如果群已创建但邀请失败，接口仍返回 created: true、新群的 group_id 以及 invite_error，调用方不应自动重试整个创建请求，以免生成重复群聊。

设置群聊普通成员的邀请策略。接口会先读取 Android QQ 群详情，只修改对应权限位，提交后再次读取并校验结果，避免覆盖其他群设置。

const result = await api.set_group_member_invite_policy({
  self_id: 1060221,
  group_id: 123456789,
  policy: "require_approval",
})

成功时返回群号、回读后的策略、底层权限位以及 read_back_verified: true。

单独开启或关闭一个群成员权限。接口使用 Android QQ 9.2.70 群详情与群设置链路，并在提交后回读验证。

const result = await api.set_group_member_permissions({
  self_id: 1060221,
  group_id: 123456789,
  permission: "invite",
  allow: true,
})

成功时返回修改后的权限位与 read_back_verified: true。

设置新加入群聊的成员是否可以查看入群前的历史消息。接口使用 Android QQ 9.2.70 的群设置链路，并在提交后回读校验。

const result = await api.set_group_new_member_history_visibility({
  self_id: 1060221,
  group_id: 123456789,
  visible: true,
})

成功时返回群号、当前可见状态、底层群标志位以及 read_back_verified: true。

设置群聊的入群验证方式。请求使用 Android 9.2.70 群资料协议写入，并在写入后重新读取群资料确认生效。

await api.set_group_add_option({
  self_id: 1060221,
  group_id: 123456789,
  add_type: 4,
  group_question: "请说明来意",
  group_answer: "",
})

成功时返回群号、最终验证类型、问题、答案和 read_back_verified: true。只有群主或有相应权限的管理员可以修改。

设置群聊的搜索开关。请求使用 Android 9.2.70 群资料协议写入，并在写入后重新读取确认。

await api.set_group_search({
  self_id: 1060221,
  group_id: 123456789,
  no_finger_open: 1,
  no_code_finger_open: 0,
})

两个搜索字段至少填写一个；未填写的字段保持不变。成功响应包含最终值和 read_back_verified: true。

设置机器人账号加入群聊时的准入方式。接口使用 Android QQ 的 OidbSvcTrpcTcp.0xf00_3 写入，并通过 OidbSvcTrpcTcp.0xef0_1 回读确认服务器已应用设置。

await api.set_group_robot_add_option({
  self_id: 1060221,
  group_id: 123456789,
  robot_member_switch: 0,
  robot_member_examine: 2,
})

两个选项至少填写一个；未填写的字段不会写入，原设置保持不变。常用组合：

• 0 / 0：允许机器人直接入群。
• 0 / 2：允许机器人申请，需管理员审核。
• 1 / 2：禁止机器人入群。

成功返回 null，与 NapCat action 契约一致。返回成功前，框架已完成回读校验。只有群主或具备相应权限的管理员可以修改。

查询当前 QQ 在指定群聊中使用 @全体成员 的权限与剩余次数。

const result = await api.get_group_at_all_remain({
  self_id: 106606,
  group_id: 106500,
})

成功时返回：

{
  "can_at_all": true,
  "remain_at_all_count_for_uin": 20,
  "remain_at_all_count_for_group": 20,
  "prompt_message_for_uin": "剩余20次",
  "prompt_message_for_group": "",
  "show_at_all_label": true
}

次数和权限由 QQ 服务端根据账号身份、群设置与当前限额实时计算，框架不会自行推算。

获取指定群聊的群荣誉数据。框架使用当前 QQ Android 9.2.70 的登录态访问 QQ 群荣誉服务，返回实时的龙王、群聊之火、群聊炽焰和快乐源泉榜单。

const honor = await api.get_group_honor_info({
  self_id: 106606,
  group_id: 106500,
  type: 'all',
})

返回字段与 Go-CQHTTP / OneBot 兼容：

{
  "group_id": 106500,
  "current_talkative": {
    "user_id": 106606,
    "nickname": "群成员",
    "avatar": "https://example.com/avatar.jpg",
    "description": "连续活跃信息"
  },
  "talkative_list": [],
  "performer_list": [],
  "legend_list": [],
  "emotion_list": [],
  "strong_newbie_list": []
}

QQ 当前已不再提供“冒尖小春笋”榜单，因此 strong_newbie_list 保留兼容字段并返回空数组。指定单一 type 时，其他榜单字段仍存在但为空数组，方便调用方使用固定结构解析。

获取指定群聊的精华消息列表。请求直接使用 QQ Android 9.2.70 APK 中保留的 OidbSvc.0xf10 协议，不依赖 PC QQ 数据库或网页端登录缓存。

const messages = await api.get_essence_msg_list({
  self_id: 1060221,
  group_id: 123456789,
})

成功时返回数组，每项包含 msg_seq、msg_random、sender_id、sender_nick、operator_id、operator_nick、message_id、operator_time 和 content。

content 会把安卓协议中的文本、QQ 表情、图片、文件与分享内容转换为标准消息段。Android 9.2.70 的 0xf10 回包本身不携带发送者和操作者的数字 QQ；框架会优先使用最近消息索引补齐发送者 QQ，无法可靠补齐的数字字段返回 0，不会伪造账号。

获取指定群聊中的公告。接口使用当前 QQ Android 9.2.70 登录态取得 skey 与 qun.qq.com 的 p_skey，再调用 QQ 官方群公告接口；不依赖 PC QQ 的本地数据库或 NodeIKernel 服务。

const notices = await api._get_group_notice({
  self_id: 1060221,
  group_id: 123456789,
})

成功时返回公告数组，每项包含 sender_id、publish_time、notice_id、message、settings 与 read_num。message.image 和 message.images 内容相同，兼容两种 OneBot 客户端字段写法。

账号必须已登录，且对目标群具有查看公告的权限。登录态失效或 p_skey 无法刷新时会直接返回错误，不会使用浏览器缓存代替。

在指定 QQ 群发布公告。框架使用当前 QQ Android 9.2.70 登录态访问 QQ 官方群公告接口，不依赖 PC QQ 的本地服务。

const result = await api._send_group_notice({
  self_id: 123456789,
  group_id: 987654321,
  content: '公告内容',
  image: 'base64://...'
})

参数

返回

{
  "notice_id": "公告 ID"
}

账号需要拥有发布群公告的权限。图片会先上传到 QQ 群公告图片接口，再将返回的图片 ID 和尺寸随公告正文发布。可用 _get_group_notice 回读，并用 _del_group_notice 删除。

删除指定群聊中的公告。接口沿用当前 QQ Android 9.2.70 登录态访问 QQ 官方群公告接口，不依赖 PC QQ 能力。

await api._del_group_notice({
  self_id: 1060221,
  group_id: 123456789,
  notice_id: "公告 ID",
})

成功时返回空数据。账号必须拥有删除该公告的管理权限；QQ 返回权限或登录态错误时，框架会保留错误码和提示，不会误报成功。

获取指定群聊当天的打卡成员列表。接口使用当前 QQ Android 9.2.70 登录态和 qun.qq.com 的 p_skey 调用 QQ 官方打卡 TRPC，不依赖 PC QQ 内核。

const members = await api.get_group_signed_list({
  self_id: 1060221,
  group_id: 123456789,
})

成功时返回数组，每项包含：

• user_id：打卡成员 QQ；
• nick：群内昵称；
• time：打卡时间戳；
• rank：框架按 QQ 返回值换算后的实际排名。

账号必须已登录并能访问该群；登录态失效或没有查看权限时会返回 QQ 原始错误。

分页获取群相册列表。接口直接调用 QQ Android 的 QunAlbum.trpc 服务，不依赖 PC QQ。

const result = await api.get_qun_album_list({ self_id: 1060221, group_id: 123456789, attach_info: '' })

返回 album_list、attach_info 和 has_more。相册项包含 ID、名称、说明、上传数量、时间、创建者和封面信息。

分页获取指定群相册中的图片和视频。

const result = await api.get_group_album_media_list({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', attach_info: '' })

返回 media_list 和前后页游标。媒体项保留 lloc、batch_id、上传者、上传时间及图片/视频地址，供评论、点赞和删除接口使用。

向已有群相册上传图片。框架使用当前 Android QQ 的 Qzone 登录态创建会话并分片上传。

await api.upload_image_to_qun_album({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', album_name: '相册名称', file: 'https://example.com/a.jpg' })

单文件上限 100 MiB。成功返回 photo_id 和图片地址。

评论群相册中的指定媒体。

await api.do_group_album_comment({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', lloc: 'media-lloc', content: '评论内容' })

self_id、group_id、album_id、lloc、content 均必填。lloc 从 get_group_album_media_list 的图片或视频封面信息中取得。

点赞群相册的一批上传内容或其中一项媒体。

await api.set_group_album_media_like({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', batch_id: '1234567890', lloc: 'media-lloc' })

self_id、group_id、album_id、batch_id 必填；lloc 可选。两者都可从媒体列表响应取得。

取消群相册媒体点赞。参数与 set_group_album_media_like 相同。

await api.cancel_group_album_media_like({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', batch_id: '1234567890', lloc: 'media-lloc' })

lloc 为空时取消整批点赞；填写时取消指定媒体的点赞。

删除群相册中的图片或视频。

await api.del_group_album_media({ self_id: 1060221, group_id: 123456789, album_id: 'album-id', lloc: 'media-lloc' })

self_id、group_id、album_id、lloc 均必填。删除视频时可以填写视频 ID 或封面 lloc；框架会先读取媒体列表，补齐 QQ 删除协议需要的封面标识和批次 ID。

使用当前在线 QQ 的 Android 9.2.70 登录态获取群文件根目录。接口会自动处理 QQ 服务端分页，并分别返回文件与文件夹。

const result = await api.get_group_root_files({
  self_id: 1060221,
  group_id: 106500,
  file_count: 50,
})

返回值包含 files 和 folders。文件字段包括 file_id、file_name、busid、file_size、upload_time、dead_time、modify_time、download_times、uploader、uploader_name 与 parent_folder_id；文件夹字段包括 folder_id、parent_folder_id、folder_name、creator、creator_name 和 total_file_count。

该接口是只读操作，账号必须已加入目标群并具有查看群文件的权限。

获取指定群文件夹中的文件与子文件夹。底层使用 QQ Android 9.2.70 群文件协议，不依赖 PC QQ 本地数据库。

const result = await api.get_group_files_by_folder({
  self_id: 1060221,
  group_id: 106500,
  folder_id: '/3d7e7839-1512-4e77-bb69-aa66124c603b',
  file_count: 50,
})

返回结构与 get_group_root_files 相同。接口会自动读取后续分页，不需要调用方维护分页游标。

获取群文件数量限制和存储空间使用情况。

const info = await api.get_group_file_system_info({
  self_id: 1060221,
  group_id: 106500,
})

成功时返回：

{
  file_count: 33,
  limit_count: 1500,
  used_space: 207497295,
  total_space: 10737418240,
}

空间字段单位为字节，数值来自 QQ 群文件服务端。

在群文件根目录创建文件夹。

await api.create_group_file_folder({
  self_id: 1060221,
  group_id: 106500,
  folder_name: 'API 测试资料',
})

成功时返回 ret_code: 0 以及本次提交的群号和文件夹名称。

删除指定群文件夹。

await api.delete_group_folder({
  self_id: 1060221,
  group_id: 106500,
  folder_id: '/3d7e7839-1512-4e77-bb69-aa66124c603b',
})

成功时返回 ret_code: 0。

将本地文件或可下载的 HTTP(S) 文件真实上传到群文件。上传完成后，文件会直接出现在 QQ 群文件列表中。

const result = await api.upload_group_file({
  self_id: 1060221,
  group_id: 106500,
  file: 'D:/Mengka-NT/files/report.txt',
  name: 'report.txt',
  folder: '/',
})

成功时返回 file_id、file_name、busid、file_size 和 parent_folder_id。这些字段可直接用于后续查询或删除。

删除指定群文件。

await api.delete_group_file({
  self_id: 1060221,
  group_id: 106500,
  file_id: '/e2ca26cc-d974-4968-9b71-eec65c9e8590',
})

成功时返回 ret_code: 0。仅提供 file_id 即可使用；框架会递归查询文件列表并补齐删除所需的业务 ID 和父文件夹。

重命名指定群文件。

调用

await api.rename_group_file(self_id, group_id, file_id, '新文件名.zip')

成功返回 { ok: true }。

将指定群文件移动到另一目录。

调用

await api.move_group_file(self_id, group_id, file_id, target_parent_directory)

成功返回 { ok: true }。

获取 Bot 的完整群聊列表。萌卡NT会自动完成分页。

调用

const result = await api.get_group_list(self_id)

参数

返回值

{
  groups: [],
  total_count: 0,
  self_uin: 123456789,
}

获取指定群的完整成员列表。

调用

const result = await api.get_group_member_list(self_id, group_id)

参数

返回值

{
  group_id: 987654321,
  members: [],
  total_count: 0,
}

成员常用字段包括 uin、nickname、card、level、title、join_time 和 last_speak_time。

获取 Bot 的群聊系统通知列表。

调用

const result = await api.get_group_system_notifications(self_id)

参数

返回值

{
  notifications: [],
  total_count: 0,
}

通知中的 request_id、request_type 与 request_extra 可用于处理入群申请。

同意入群申请。

调用

const result = await api.approve_group_apply(
  self_id,
  group_id,
  request_id,
  request_type,
  request_extra,
)

参数

请求字段来自 group_notice/apply 事件或 get_group_system_notifications。

返回值

返回申请处理结果。

拒绝入群申请。

调用

const result = await api.reject_group_apply(
  self_id,
  group_id,
  request_id,
  request_type,
  reason,
  request_extra,
)

参数

返回值

返回申请处理结果。

同意好友发来的群聊邀请。

调用

const result = await api.approve_group_invite(self_id, group_id, msgseq)

参数

group_id 和 msgseq 从 get_group_system_notifications 返回的同一条邀请通知中取得。 框架会按 QQ Android 9.2.70 返回的实际通知类型处理，不再把邀请类型写死。

返回值

返回邀请处理结果。请求已处理或已失效时会返回错误，不会伪造成功结果。

测试环境已完成真实链路验证：框架向 1060221 发出群 106500 的邀请，用户在 QQ 客户端确认后，框架通过群成员查询确认该账号已入群。

设置或取消群聊管理员。

调用

const result = await api.set_group_admin(
  self_id,
  group_id,
  target_uin,
  set_admin,
)

参数

返回值

{
  group_id: 987654321,
  target_uin: 112233445,
  set_admin: true,
}

修改指定群成员的群名片（群昵称），也可以传空字符串清空群名片。

修改其他成员时，当前 Bot 需要是群主或管理员；普通成员只能修改自己的群名片。最终权限由 QQ 群设置和服务器校验决定。

调用

const result = await api.set_group_card(
  self_id,
  group_id,
  user_id,
  card,
)

参数

返回值

{
  success: true,
  group_id: 106500,
  user_id: 1060221,
  card: '萌卡测试昵称',
}

清空群名片时，返回值中的 card 为 ''。

示例

await api.set_group_card(2082083, 106500, 1060221, '新群昵称')

// 清空群名片
await api.set_group_card(2082083, 106500, 1060221, '')

执行群聊打卡。

调用

const result = await api.group_sign(self_id, group_id)

参数

返回值

返回打卡文案、累计天数、群排名、详情地址与结构化响应字段。

设置或取消群聊成员禁言。

调用

const result = await api.set_group_mute(
  self_id,
  group_id,
  target_uin,
  duration_sec,
)

参数

返回值

{
  group_id: 987654321,
  target_uin: 112233445,
  duration_sec: 600,
}

开启或取消全员禁言。

调用

const result = await api.set_group_mute_all(self_id, group_id, mute)

参数

返回值

{ group_id: 987654321, mute: true }

设置或清除群聊成员的专属头衔。目标成员昵称由服务端通过 QQ 名片接口自动获取。

调用

const result = await api.set_group_special_title(
  self_id,
  group_id,
  user_id,
  title,
)

参数

返回值

{
  success: true,
}

将指定成员移出群聊，可同时拒绝该成员后续的加群申请。

调用

const result = await api.kick_group_member(
  self_id,
  group_id,
  user_id,
  reject_add_request,
)

参数

返回值

{
  success: true,
}