2023 年最新 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 机器人设置

Token 和 AppSecret

请妥善保管 QQ 机器人令牌 Token(用于以机器人身份调用 openapi) 和 机器人密钥 AppSecret (用于在 oauth 场景进行请求签名的密钥)

在这里插入图片描述
消息 URL 配置

机器人发送的消息中包含的 URL 必须先在这里设置,消息才可以下发生效。域名需经过ICP备案,新备案域名 24 小时后才可以配置,请下载校验文件,并将文件放置在域名根目录下,并确保可访问该文件。

在这里插入图片描述

频道用户意见反馈

为了帮助开发者获取 C 端用户对于机器人的评价与反馈,平台在频道场景为开发者接入了"兔小巢反馈空间",开发者可以通过创建产品反馈空间。

在这里插入图片描述

频道用户意见反馈: 点击进入登陆后,根据提示创建产品,将会获得一个兔小巢反馈空间,C 端用户所填写的机器人反馈将同步至此空间,开发者以后可登陆此空间查看用户反馈。

产品 ID 填写: 需要在此处填写兔小巢反馈空间的产品 ID,C 端用户的机器人反馈才可同步至此处,详细获取路径如开发者端提示:设置 > 产品设置 > 产品 ID。

QQ 机器人 SDK

SDK链接地址
Node.Js SDK 文档https://bot.q.qq.com/wiki/develop/nodesdk/
Python SDK 文档https://bot.q.qq.com/wiki/develop/pythonsdk/
GoLang SDK 文档https://bot.q.qq.com/wiki/develop/gosdk/

安装 QQ 机器人 Node.Js SDK

npm i qq-guild-bot

# 或者使用yarn
yarn add qq-guild-bot

# 国内安装可以使用腾讯源
npm i qq-guild-bot --registry=https://mirrors.tencent.com/npm/

配置 .env:在根目录创建 .env 环境变量配置文件

appID=102075492
token=你的token
AppSecret=你的AppSecret

qq-guild-sdk 更新

打开 node_modules > qq-guild-sdk

因为 qq-guild-sdk 不支持 QQ 群消息监听处理,需要使用调整后的 qq-guild-sdk 新的 Node 模块包,同学们点击下载之后,把原先的 qq-guild-sdk 模块包整个进行替换即可。

调整后 qq-guild-sdk Node 模块包:下载地址

websocket 监听

QQ 机器人 创建 WS 实例并监听消息

import { createWebsocket } from 'qq-guild-bot';
const ws = createWebsocket(testConfigWs);
ws.on('READY', data => {
    console.log('[READY] 事件接收 :', data);
});
ws.on('ERROR', data => {
    console.log('[ERROR] 事件接收 :', data);
});
ws.on('GUILDS', data => {
    console.log('[GUILDS] 事件接收 :', data);
});
ws.on('GUILD_MEMBERS', data => {
    console.log('[GUILD_MEMBERS] 事件接收 :', data);
});
ws.on('GUILD_MESSAGES', data => {
    console.log('[GUILD_MESSAGES] 事件接收 :', data);
});
ws.on('GUILD_MESSAGE_REACTIONS', data => {
    console.log('[GUILD_MESSAGE_REACTIONS] 事件接收 :', data);
});
ws.on('DIRECT_MESSAGE', data => {
    console.log('[DIRECT_MESSAGE] 事件接收 :', data);
});
ws.on('INTERACTION', data => {
    console.log('[INTERACTION] 事件接收 :', data);
});
ws.on('MESSAGE_AUDIT', data => {
    console.log('[MESSAGE_AUDIT] 事件接收 :', data);
});
ws.on('FORUMS_EVENT', data => {
    console.log('[FORUMS_EVENT] 事件接收 :', data);
});
ws.on('AUDIO_ACTION', data => {
    console.log('[AUDIO_ACTION] 事件接收 :', data);
});
ws.on('PUBLIC_GUILD_MESSAGES', data => {
    console.log('[PUBLIC_GUILD_MESSAGES] 事件接收 :', data);
});

监听 QQ 群消息

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

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

const client = createOpenAPI(testConfig);
const ws = createWebsocket(testConfig);

ws.on('GROUPS', data => {
    console.log('Gourp messgae:', data);
});

配置说明

参数说明类型
appIDQQ 机器人 ID(QQ 开放平台机器人管理端获得)String
token机器人身份调用 openapi(QQ 开放平台机器人管理端获得)String
shards配置 QQ 机器人分布式部署 [集群编号, 集群数量]Array
intentsQQ 机器人事件类型订阅Array
sandboxQQ 机器人是否开启沙箱测试Boolean

intents 可选值举例:[‘GUILDS’, ‘GUILD_MEMBERS’, ‘GUILD_MESSAGES’,‘GUILD_MESSAGE_REACTIONS’,‘DIRECT_MESSAGE’, ‘INTERACTION’,‘MESSAGE_AUDIT’,‘FORUMS_EVENT’,‘AUDIO_ACTION’, ‘PUBLIC_GUILD_MESSAGES’]

事件类型的订阅,是有权限控制的,除了 GUILDS,PUBLIC_GUILD_MESSAGES,DIRECT_MESSAGE,GUILD_MEMBERS 事件是基础的事件,默认有权限订阅之外,其他的特殊事件,都需要经过申请才能够使用,如果在鉴权的时候传递了无权限的 intents,websocket 会报错,并直接关闭连接。

特别注意:intents传空数组时,将默认开启全部事件类型的监听。

群消息 group message

Gourp messgae: {
  eventType: 'GROUP_AT_MESSAGE_CREATE',
  eventId: 'GROUP_AT_MESSAGE_CREATE:h2wlsxge4luozgoigwumbriafsda7kdjiuwpmwrrlxqkgxwpynhysl6q6ws849',
  msg: {
    author: {
      id: 'E2976D3827112BFBB2ED537533A36DF1',
      member_openid: 'E2976D3827112BFBB2ED537533A36DF1'
    },
    content: ' 测试',
    group_id: 'A85B11B27A39FB0C238B0F19FA09DDF7',
    group_openid: 'A85B11B27A39FB0C238B0F19FA09DDF7',
    id: 'ROBOT1.0_h2WlSxGE4lUOz.gOiGwumPXNIo3bQDNfDUL9B6RR64rOz1lFtaet2maxZIYEGiAlunES0n.7u0HtihQXiTG9mw!!',
    timestamp: '2023-11-11T23:32:29+08:00'
  }
}

获取接口凭证

截止当前日期 2023 年 11 月 10 日,腾讯 BOT 机器人官方还没更新相关 SDK,所以需要进行调用群 API 则需要 POST 请求进行处理,我们通过 axios 库获取接口凭证。

安装 axios 第三方库

npm install axios

接口凭证 请求参数设置

clientSecret / AppSecret:oauth 场景进行请求签名的密钥(QQ 开放平台机器人管理端获得)String
在这里插入图片描述

接口凭证请求地址:https://bots.qq.com/app/getAppAccessToken

调用 axios 请求获取接口凭证

const axios = require('axios')
const { config } = require("dotenv")
config()

let data = {
    appId: process.env.appId,
    clientSecret: process.env.AppSecret
}

axios.post('https://bots.qq.com/app/getAppAccessToken', data)
    .then(res => {
        console.log(res.data)
    })
    .catch(err => {
		console.log(err)
    })

请求错误:data: { code: 100016, message: ‘invalid appid or secret’ }

acesss_token 返回结果示例

data: {
	access_token: '2HEWxcMy12Vc3ZC3yIgWxJcnilSp-gdXjtdLmP_yFief3wQMPQuWUzu5cFKhsAnIjPFRAUXPajLl',
	expires_in: '7200'
}

在这里插入图片描述

目前 access_token 生命周期默认 7200 秒,每次请求不会刷新新的 access_token,开发者需要在过期后自行刷新 access_token,保证调用链路权限正常。

group 群接口调用

在每次调用 https 的 openapi 开放接口请求的时候,需要在 header 内引入 access_token 进行调用权限验证。

统一地址

https://api.sgroup.qq.com

在这里插入图片描述

QQ 发送群消息

通过 v2 post 发送群消息 基本:HTTP URL /v2/users/{openid}/messages

在这里插入图片描述
具体代码展示

const axios = require('axios')
const { config } = require("dotenv")
config()

const axiosconfig = {
    headers:{
        'Authorization': "QQBot 【access_token】",
        'X-Union-Appid': "102075492",
    }
};

let data = {
    content: "Nonebot Perfect",
    msg_type: 1,
    image: "https://i2.hdslb.com/bfs/face/41c1233ac533fb5e03cd325e0e70c0b9fa87f841.jpg"
}

axios.post('https://api.sgroup.qq.com/v2/groups/A85B11B27A39FB0C238B0F19FA09DDF7/messages', data, axiosconfig)
.then(res => {
    console.log(res.data)
})
.catch(err => {
    console.log(err)
})

发送媒体消息(图片类型)

属性类型必填说明
file_typeint媒体类型:1 图片,2 视频,3 语音,4 文件(暂不开放)资源格式要求图片:png / jpg,视频:mp4,语音:silk
urlstring需要发送媒体资源的url
srv_send_msgbool设置 true

具体代码展示

const axios = require('axios')
const { config } = require("dotenv")
config()

const axiosconfig = {
    headers:{
        'Authorization': "QQBot 【access_token】",
        'X-Union-Appid': "102075492",
    }
};

let file = {
    file_type: 1,
    url: "https://i2.hdslb.com/bfs/face/41c1233ac533fb5e03cd325e0e70c0b9fa87f841.jpg",
    srv_send_msg: true
}

axios.post('https://api.sgroup.qq.com/v2/groups/A85B11B27A39FB0C238B0F19FA09DDF7/files', file, axiosconfig)
    .then(res => {
        console.log(res.data)
    })
    .catch(err => {
        console.log(err)
    })

QQ 群聊事件监听

发送消息分为,主动推送与被动回复,主动消息和被动消息在不同的场景下,发送的频次有不同的规则。 发送消息的接口有4个场景:QQ单聊、QQ群聊、文字子频道、频道私信。

const axios = require('axios')
const { config } = require("dotenv")
config()

const axiosconfig = {
    headers:{
        'Authorization': "QQBot wjy2j3CIDvFmN0HyPEPO-nwJOGpis2krvDtmxsiJwMKxI9lIY_ZoN73uVKtrMmViut_mHOdz70h8gw",
        'X-Union-Appid': "102075492",
    }
};

let data = {
    content: "Nonebot Perfect",
    msg_type: 0
}

axios.post('https://api.sgroup.qq.com/v2/groups/A85B11B27A39FB0C238B0F19FA09DDF7/messages', data, axiosconfig)
    .then(res => {
        console.log(res)
    })
    .catch(err => {
        console.log(err)
    })

响应结果结构

事件接收 : {
	eventType: 'GROUP_AT_MESSAGE_CREATE',
	eventId: 'GROUP_AT_MESSAGE_CREATE:qdtawy6rufj9ziciulptyfvpd84zm7lk9q6pumnyjuv957wseidnfe0ixfc6s',
	msg: {
		author: {
			id: '7193745BFE7C7D3C30C96678ABBB5F48',
			member_openid: '7193745BFE7C7D3C30C96678ABBB5F48'
		},
		content: ' 12434',
		group_id: 'A85B11B27A39FB0C238B0F19FA09DDF7',
		group_openid: 'A85B11B27A39FB0C238B0F19FA09DDF7',
		id: 'ROBOT1.0_QD.TAWY6RUfJ9ZicIULpTzch-F9MKMiKg1RG04Gel8V2I.0HgXgR0D8UfhgqMN2Jy0bzWi8-PDzwfCMemkroZw!!',
		timestamp: '2023-11-10T10:44:07+08:00'
	}
}

ffmpeg 音频格式

在这里插入图片描述

下载地址:https://github.com/BtbN/FFmpeg-Builds/releases

ffmpeg 工具 bin 目录

在这里插入图片描述

配置 ffmpeg/bin 系统环境变量

在这里插入图片描述

QQ 被动回复语音

配置功能 api 地址

let groupApiUrl = (groupOpenid, mode) => {
    return `https://api.sgroup.qq.com/v2/groups/${groupOpenid}/${mode}`
}

发送群消息 sendGroupAudio 语音函数

let sendGroupAudio = (msgid, url, groupOpenid) => {
    let file = {
        file_type: 3,
        url: url,
        srv_send_msg: false
    }
    axios.post(groupApiUrl(groupOpenid, "files"), file, axiosConfig).then(res => {
        let data = {
            content: " ",
            msg_type: 7,
            media: { file_info: res.data.file_info },
            msg_id: msgid
        }
        axios.post(groupApiUrl(groupOpenid, "messages"), data, axiosConfig).then(res => {
            console.log(res.data)
        }).catch(err => {
            console.log(err)
        })
    }).catch(err => {
        console.log(err)
    })
}

机器人启动代码

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

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

const axiosConfig = {
    headers: {
        'Authorization': `QQBot ${process.env.access_token}`,
        'X-Union-Appid': process.env.appID,
    }
};

const ws = createWebsocket(testConfig);

ws.on('GROUPS', data => {
    console.log('Gourp messgae:', data);
    const msgid = data.msg.id
    let groupOpenid = "A85B11B27A39FB0C238B0F19FA09DDF7"
    sendAudio(msgid, "https://xxx.com/qq.silk", groupOpenid)
});

特别注意:发送语音文件格式必须是 Tencent silk 语音格式

运行测试

在这里插入图片描述

silk 格式转换处理

Node 异步请求获取 mp3 文件

const axios = require('axios')
const fs = require('fs')

let getAudio = (content) => {
    axios({
        method: 'get',
        url: `https://api.vvhan.com/api/song?txt=${content}`,
        responseType: 'stream',
    }).then(res => {
        let ws = fs.createWriteStream('initaudio.mp3')
        res.data.pipe(ws);
        ws.on('finish', () => {
            console.log('finish')
        })
    }).catch(err => {
        console.log(err);
    });
}

Node 同步请求获取 mp3 文件

let getAudioSync = async (content) => {
    let response = await axios({
        method: 'get',
        url: `https://api.vvhan.com/api/song?txt=${content}`,
        responseType: 'stream',
    })
    const reader = response.data;
    const writer = fs.createWriteStream('initaudio.mp3');
    reader.pipe(writer);
    return new Promise((resolve, reject) => {
        writer.on('finish', resolve);
        writer.on('error', reject);
    });
}

格式转换操作

let encodeSilk = () => {
    execSync('ffmpeg -i "initaudio.mp3" -f s16le -ar 24000 -ac 1 -acodec pcm_s16le "outaudio.pcm"');
    execSync('silk_v3_encoder "outaudio.pcm" "qq.silk" -tencent')
}
软件名称:梦想接口工作室 -- QQ机器人! 软件版本:1.0.0.1 更新日期:2010/7/19 软件作者:小胡 软件下载地址:http://www.8han.com/qq/down/QQRobot.rar 软件说明: 1.在论坛:http://www.8han.com 论坛中注册一个账号。然后用账号登陆软件。 2.登陆成功后输入QQ账号和密码。点击登陆,如果QQ好友比较多,就会比较慢,因为每次登陆都会下载好友信息和信息。 3.在实时日志中就能看到QQ机器人的动作。 4.配置修改中,可以修改QQ机器人的默认语句和问答语句。 5.论坛整合中需要输入论坛的数据库信息。 6.设置 数据库信息 注:数据库前缀不要下划线,论坛地址后面不要加“/” 7.QQ号有2层含义,1.与论坛绑定的号,如若发现论坛有新帖,机器人就会向所设置的号中发信息,2锁定的号,因为考虑到有的用户,不想让机器人在别的中说话,所以就可以锁定机器人只在锁定的中发言。 8.如果在使用的过程中遇到问题,可以在论坛中提交问题,请经常查看版本信息,获取最新QQ机器人版本。 函数讲解: 1.默认回答中的函数:$qq$:收到信息的发送QQ。 $qm$ :收到的信息。 2.论坛主贴通知新信息:$author$ :帖子的发送人 $subject$:帖子的标题 $url$:帖子的地址 3.论坛主贴通知新信息:$tauthor$ :帖子的发送人 $author$ :帖子的回复人 $subject$:帖子的标题 $url$:帖子的地址 $views$ : 浏览次数 $replay$ :回复次数 命令详解: help:列出所有命令集 s:www.8han.com 查询8han.com的收录情况和PR值 e:english 把英文翻译为中文 c:中国 把中文翻译为英文 j:中国 把简体翻译成繁体 f:中國 把繁体翻译成简体 软件调试成功后,论坛中发新帖会在绑定的QQ中发言。 论坛中发新回帖会给发帖的楼主发信息。 QQ机器人2010-7-22 更新日志: 1.版本由1.0.0.1升级至1.0.0.2 2.简约了登陆界面 3.解决了缩小就关闭的问题,软件制作成:关闭就关闭了软件,但是做出了QQ一样的缩进效果! 4.软件增加了测试论坛链接成功与否按钮 5.论坛版块中,点击了开始监控,才监控论坛。
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

唤醒手腕

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值