QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第一期]

QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第一期]

第一期介绍：开发环境，基础框架，接口调用与用户鉴权

---

不懂得的也可以来私聊或评论区问哦～
本来给大家分享了笔者的微信公众号和讨论QQ群方便大家交流，奈何审核不给过，偏说我打广告，那只能不发了，欸。

---

前言

前段时间发现了QQ频道机器人这个好玩的东西，ChatGPT爆火之后，各类通讯APP接入ChatGPT也是如雨后春笋般冒出，前段时间我用QQ频道机器人官方PythonSDK编写了接入国产大模型的文章，感兴趣的可以去看我的这篇文章：QQ 腾讯官方机器人搭建。

但是我开始不满足使用官方SDK来搭建，毕竟使用官方SDK来搭建的局限性太大了，从这篇文章开始，我会对QQ官方机器人文档进行逐一剖析，让大家可以不使用官方SDK来搭建QQ频道机器人，本文主要使用python和C#语言举例。

阅读本文的前提：一台电脑，python 3.x，注册好的QQ机器人(具体内容详见QQ 腾讯官方机器人搭建)，手(用来三连😍)

笔者学业繁重，编写此文旨在帮助那些QQ频道机器人热爱者(新手)，虽学业繁重，但能帮助大家，也是对此乐此不疲，还望多多支持。

起步指南

账号注册

QQ机器人：一个机器人可以被添加到 群聊/频道 内对话，QQ用户也可以直接跟机器人 单独对话 。

开发者账号主体要求：

• 单聊对话：[定向邀请]
• 群聊场景：仅支持企业主体[个人主体暂不支持]
• 频道场景：企业主体与个人主体均可申请

注册地址：QQ开放平台

注册创建机器人后：获得的开发机器人接入票据 App ID AppSecret Token

名称	描述	备注
AppID	机器人ID	必须使用
AppSecret	机器人密钥	用于在 oauth 场景进行请求签名的密钥
Token	机器人 Token	可用于调用开放接口的鉴权，建议使用更安全的 access token 的鉴权方式

💡在QQ开放平台 App ID AppSecret Token是你需要获取的值，这在后面是你调用QQ机器人的重要凭证。

用户端功能简介

基础消息对话

对话场景

机器人可以被添加各种聊天场景下

单聊	群聊	文字子频道	频道私信

消息类型

在对话场景里面可以使用的消息类型，以下消息类型均涉及。
- 文本
- 表情
- 图片
- 图文
- 视频
- 语音
- 文件
- Ark 消息
- Embed 消息
- Markdown 消息

指令面板

输入 / 或者 @机器人，唤起的一个操作面板，开发者可在机器人管理端自定义设置展示内容和点击动作。

/	@

自定义菜单

在单聊场景下有一个’快捷菜单’面板，开发者可在机器人管理端自定义设置里面的按钮内容和按钮动作。

消息交互

在各种消息场景内，开发者可在消息体上实现自定义一些与用户的交互方式。

消息按钮	文字链

资料卡与设置

说明
在机器人资料页里，包含有基本介绍展示、服务跳转、指令介绍与使用、基本设置、添加删除机器人等功能。

• 功能介绍
• 服务与指令
• 设置相关
• 添加使用

分享推荐与搜索

说明
在添加与发现场景内，逐步开放更多的发现路径。

分享机器人	群管理推荐位	频道管理推荐位	群聊加号面板
支持	支持	支持	暂未支持

机器人QQ号搜索	昵称搜索	机器人分类搜索
支持	暂未支持	暂未支持

基础框架须知

前面都是QQ机器人文档给的内容，接下来我会详细介绍QQ机器人的详细框架，为后续搭建机器人奠定基础

接口通信基础框架

接口通信基础框架，BOT 开发者对接 QQ 机器人开放平台提供的接口能力，开发出一款让普通 QQ 用户可用的机器人。

QQ用户将消息发送给机器人，而QQbot开发者有两种方式调用QQ机器人来处理用户消息和控制QQ机器人。
第一种是openapi，第二种是websocket。 前者 使用https方式，更倾向于一次性操作，例如你想要创建一个频道或者子频道，当然你还可以调用api进行更加复杂的操作； 后者 使用WebSocket 方式，可以持续监听机器人所处环境。

接口调用与鉴权

说明
QQ 机器人服务端开放的 openapi 接口，均使用 https 方式进行调用，通过 AccessToken 机制实现对 openapi 接口调用的鉴权。

在调用QQ机器人时，你的 herders 请求中需要包含 Authorization ，如何获取呢？需要完成下面两步：1.获取调用凭证；2.鉴权方式

获取调用凭证

请求地址(HTTP URL)：https://bots.qq.com/app/getAppAccessToken
请求方式(HTTP Method)：POST
请求参数(appId,clientSecret也就是前面获取的appid和appsercet)
返回参数(access_token)：获取到的凭证 Authorization
返回参数(expires_in)：凭证有效时间，单位：秒。目前是7200秒之内的值
错误码：0 = ok

到这里，新手可能就蒙了，这咋整呢？按照我的方法一步一步来：
调用示例(python)

import requests  # 导入requests库，用于发送HTTP请求

# 定义请求的URL，这是QQ机器人获取AccessToken的接口地址
url = "https://bots.qq.com/app/getAppAccessToken"

# 定义请求头，设置Content-Type为application/json，表示发送的是JSON格式的数据
headers = {
    "Content-Type": "application/json"
}

# 定义请求的数据，这里需要替换appid和appsecret为实际的值
# appId和clientSecret是在QQ机器人开放平台创建机器人时获得的凭证
data = {
    "appId": "YOUR_APP_ID",  # 替换为你的机器人的AppID
    "clientSecret": "YOUR_APP_SECRET"  # 替换为你的机器人的AppSecret
}

# 发送POST请求到指定的URL，包含请求头和请求数据
response = requests.post(url, headers=headers, json=data)

# 因为收到的格式为json格式，所以使用json()
print(response.json())

调用示例(C#)

using System; // 引入System命名空间，提供基本的类和应用程序支持
using System.Net.Http; // 引入System.Net.Http命名空间，用于发送HTTP请求
using System.Text; // 引入System.Text命名空间，用于文本处理
using System.Threading.Tasks; // 引入System.Threading.Tasks命名空间，用于支持异步操作
using Newtonsoft.Json; // 引入Newtonsoft.Json命名空间，用于处理JSON数据

class Program
{
    static async Task Main(string[] args) // 主函数，异步方式运行
    {
        // 定义appid和clientSecret变量，需要替换为实际的值
        string appid = "YOUR_APP_ID";
        string clientSecret = "YOUR_CLIENT_SECRET";

        // 创建HttpClient实例用于发送HTTP请求
        var client = new HttpClient();

        // 创建StringContent实例，包含JSON格式的请求体
        // 这里将appid和clientSecret作为JSON对象的属性进行编码
        var content = new StringContent("{\"appId\":\"" + appid + "\",\"clientSecret\":\"" + clientSecret + "\"}", Encoding.UTF8, "application/json");

        // 异步发送POST请求到指定的URL，并传递请求体
        var response = await client.PostAsync("https://bots.qq.com/app/getAppAccessToken", content);

        // 读取响应内容作为字符串
        string result = await response.Content.ReadAsStringAsync();

        // 输出响应内容
        Console.WriteLine(result);
    }
}

返回示例

{
  "access_token": "ACCESS_TOKEN",
  "expires_in": "7200"
}

说明
目前 access_token 生命周期默认 7200 秒，每次请求不会刷新新的 access_token，开发者需要在过期后自行刷新 access_token，保证调用链路权限正常。
在上一个 access_token 接近过期时间 60 秒内，获取 access_token 时，会获得一个新的 access_token，老的 access_token 在这个60秒内仍然有效。

鉴权方式

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

统一地址：https://api.sgroup.qq.com
请求头(Authorization)：格式值："QQBot ACCESS_TOKEN"

在后续的操作中我们会频繁使用鉴权方式，所以在这里大家可以将其做成函数调用。

🤗目前使用openapi方式，后续websocket方法会单独出教程，本文旨在让大家知道如何通过QQ机器人官方文档学习QQ机器人api。

唯一身份机制

不同的 bot(AppID) 获取到的用户 openid，群 openid，频道 openid 均不相同，若跨业务有关联用户身份需求，后续提供跨 AppID 绑定后，使用类似 unionid 的机制打通身份。

举个例子：不同 bot 在单聊场景，获取到的用户唯一识别 openid 不一样，称为 user_openid；不同 bot 在群聊场景，获取到的群唯一识别号 openid 不一样，称为 group_openid；相同 bot 在不同的群，获取到同一个用户在群内的唯一识别号 openid 不一样，称为 member_openid。

错误码

错误码请详见QQ机器人官方文档：openapi 错误码文档，websocket 错误码文档

致谢和更新

文章持续更新，如果三连支持，速更！！！
请在评论区提出疑惑和建议
上次更新: 9/8/2024, AM

---

如果你是小白并且你想要直接搭建一个可以调用国产AI与用户对话的QQ频道机器人，可以移步查看上一篇文章阅读学习：
⬅️[于2024/9/5第一次更新] QQ 腾讯官方机器人搭建(更新中)

➡️QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第二期]