2024 年最新使用 Node 搭建QQ开放平台官方 QQ 频道机器人详细教程（更新中）

news2025/2/24 18:57:13

注册 QQ 开放平台账号

QQ 开放平台是腾讯应用综合开放类平台，包含 QQ 机器人、QQ 小程序、QQ 小游戏等集成化管理，也就是说你注册了QQ 开放平台，你开发 QQ 机器人还是 QQ 小程序都是在这个平台进行部署上线和管理。

在这里插入图片描述
如何注册 QQ 开放平台账号？点击首页右上角【立即注册】

注意主体的选择，当然无论是企业还是个人，都是可以开发 QQ 小程序或者 QQ 机器人的，但是如果您是个人主体的话，那么你的权限将有所局限，因为部分服务权限是需要企业主体的。

企业主体入驻开发者默认支持频道、群场景开发能力；个人主体入驻开发者默认仅支持频道场景开发能力。除默认开通的能力外，后续其他接口能力申请上，企业开发者与个人开发者也存在差异。

在这里插入图片描述

温馨提示：姓名和身份证号码务必与手机号码对应运营商实名登记的信息一致，否则会提示错误。

创建 QQ 机器人

注册完成后登陆开放平台！在机器人分栏点击【创建机器人】
在这里插入图片描述
填写 QQ 机器人资料信息（名称、头像、介绍）

在这里插入图片描述
QQ 机器人管理端后台

QQ频道机器人是一种对QQ频道进行功能扩展的程序，通过开放的接口，让开发者能够实现开发出交互形式丰富的机器人，以辅助实现频道/社群内的管理、消息互动，满足频道主或群主运营者多样化、个性化的运营需求，从而提高运营效率，同时为用户带来丰富的服务和便捷的体验。

资料提交成功后，即会生成 appid，点击对应的应用即可跳转管理端。

在这里插入图片描述
机器人类型和测试频道 / 群配置

机器人类型包含私域机器人或者公域机器人。当然公域机器人对于服务器的要求过高，我们这边也可以选择私域机器人进行开发。特别注意在选择沙箱测试频道的时候，你必须提前创建个沙箱测试频道，必须＜20人的频道。但是选择沙箱测试 QQ 群则需要您是企业资质。

沙箱频道仅可设置当前用户为频道主/管理员的频道、沙箱群仅可设置当前用户为群主/群管理员的群，且沙箱频道成员、沙箱群成员不可大于20人。

在这里插入图片描述

在沙箱配置页面不同类型开发者支持开发不同场景机器人功能

建议开发者根据实际的需要，选择在不同场景开发机器人，完成对应场景的沙箱环境配置。配置沙箱后，开发者可在「功能配置」、「使用范围与人员」页面解锁相应场景的配置能力。

认证身份	QQ频道	QQ群	消息列表单聊
企业开发者	✅	✅	申请后可开发
个人开发者	✅	暂不开放	暂不开放

配置沙箱 QQ 群 / 频道，需要先在QQ客户端创建符合沙箱要求的QQ群/QQ频道。在频道场景，机器人仍然保留「公域」/「私域」机器人的区分，设置为公域机器人保存确认后不可切换为私域机器人，但在「使用范围与人员」可设置公域机器人的允许添加范围：“全部用户可添加”/“仅白名单用户可添加”。配置沙箱频道/群后，机器人会出现在沙箱频道/沙箱群的机器人列表当中。

搭建 qq-guild-bot 环境

国内安装 qq-guild-bot 使用腾讯源

npm i qq-guild-bot --registry=https://mirrors.tencent.com/npm/

配置 .env 文件：机器人信息

appId=申请机器人时获取到的机器人 BotAppID
token=申请机器人时获取到的机器人 BotToken

启动案例

const { createOpenAPI, createWebsocket } = require('qq-guild-bot');

const testConfig = {
	appID: process.env.appId,
	token: process.env.token,
	intents: ['PUBLIC_GUILD_MESSAGES'],
	sandbox: false,
};

const client = createOpenAPI(testConfig);

const ws = createWebsocket(testConfig);

配置属性说明

属性	说明	案例值
appID	申请机器人时获取到的机器人 BotAppID	process.env.appId
token	申请机器人时获取到的机器人 BotToken	process.env.token
intents	事件订阅，用于开启可接收的消息类型	[‘PUBLIC_GUILD_MESSAGES’]
sandbox	沙箱支持，可选，默认 false（v2.7.0+及以后版本）	false

请注意 process.env.appId 和 process.env.token是环境变量中存储的实际值，它们通常用于保护敏感信息，例如 API 密钥或令牌。在真实的应用程序中，您不会直接在代码中硬编码这些值，而是使用环境变量或配置文件来安全地存储和访问它们。

intents 可选值举例：

['GUILDS', 'GUILD_MEMBERS', 'GUILD_MESSAGES','GUILD_MESSAGE_REACTIONS','DIRECT_MESSAGE', 'INTERACTION','MESSAGE_AUDIT','FORUMS_EVENT','AUDIO_ACTION', 'PUBLIC_GUILD_MESSAGES']

频道 API 官方文档

QQ机器人文档：https://bot.q.qq.com/wiki/develop/api-v2/

在这里插入图片描述

频道消息事件

{
	eventType: 'AT_MESSAGE_CREATE',
	eventId: 'AT_MESSAGE_CREATE:9cf66025-fd89-4474-8cff-5b653f13b793',
	msg: {
		author: {
			avatar: 'https://qqchannel-profile-1251316161.file.myqcloud.com/1690525084d31f5da18614da93?t=1690525084',
			bot: false,
			id: '3099335931735309862',
			username: '唤醒手腕'
		},
		channel_id: '633953187',
		content: '<@!4609307794105190966> 测试',
		guild_id: '11682521373910822180',
		id: '08a4daf3e6afe9a990a20110a3b7a5ae02381a48e5add3b006',
		member: {
			seq_in_channel: '26',
			timestamp: '2024-04-09T13:49:25+08:00'
		}
	}
}

回复事件

{
	eventType: 'READY',
	msg: {
		version: 1,
		session_id: 'fb73286a-fa79-4b52-a68b-193e3380e022',
		user: {
			id: '4609307794105190966',
			username: '边缘骇客机器人-测试中',
			bot: true,
			status: 1
		},
		shard: [0, 1]
	}
	member: {
		joined_at: '2023-11-09T22:46:01+08:00',
		nick: '唤醒手腕',
		roles: [Array]
	},
	mentions: [
		[Object]
	],
	seq: 24,
	seq_in_channel: '24',
	timestamp: '2024-04-09T13:45:49+08:00'
}