2023 年最新 qq 开放平台官方企业 qq 群机器人新特性超详细教程（更新中）|电子爱好者-九游会真人第一品牌

admin管理员组

文章数量:1559037

注册 qq 开放平台账号

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

如何注册 qq 开放平台账号？点击j9九游会老哥俱乐部交流区首页右上角【立即注册】

注意主体的选择，当然无论是企业还是个人，都是可以开发 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/wiki/develop/nodesdk/
python sdk 文档	https://bot.q.qq/wiki/develop/pythonsdk/
golang sdk 文档	https://bot.q.qq/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);
});

配置说明

参数	说明	类型
appid	qq 机器人 id（qq 开放平台机器人管理端获得）	string
token	机器人身份调用 openapi（qq 开放平台机器人管理端获得）	string
shards	配置 qq 机器人分布式部署 [集群编号, 集群数量]	array
intents	qq 机器人事件类型订阅	array
sandbox	qq 机器人是否开启沙箱测试	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/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/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/bfs/face/41c1233ac533fb5e03cd325e0e70c0b9fa87f841.jpg"
}
axios.post('https://api.sgroup.qq/v2/groups/a85b11b27a39fb0c238b0f19fa09ddf7/messages', data, axiosconfig)
.then(res => {
    console.log(res.data)
})
.catch(err => {
    console.log(err)
})

发送媒体消息（图片类型）

属性	类型	必填	说明
file_type	int	是	媒体类型：1 图片，2 视频，3 语音，4 文件（暂不开放）资源格式要求图片：png / jpg，视频：mp4，语音：silk
url	string	是	需要发送媒体资源的url
srv_send_msg	bool	是	设置 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/bfs/face/41c1233ac533fb5e03cd325e0e70c0b9fa87f841.jpg",
    srv_send_msg: true
}
axios.post('https://api.sgroup.qq/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/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/btbn/ffmpeg-builds/releases

ffmpeg 工具 bin 目录

配置 ffmpeg/bin 系统环境变量

qq 被动回复语音

配置功能 api 地址

let groupapiurl = (groupopenid, mode) => {
    return `https://api.sgroup.qq/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/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/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/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')
}

本文标签： 机器人