# 接入 QQ 频道

# 应用子频道跳转链接

跳转链接分为：

子频道跳转链接：即点击子频道时跳转的地方（如开黑组队跳转到王者大厅）
外显信息跳转链接：即点击外显信息时跳转的地方（如王者开黑跳转到指定车队）

channel_link

例子（例子中的 schema 由开发商提供的小程序路径生成）：

mqqapi://miniapp/open?_atype=0&_mappid=1108797500&_mvid=&_path=xxx&_vt=4&referer=5002&via=5002_2&_sig=294259875&_nq={JUMP_SECRET}

频道默认会在链接中带上jumpSecret：

_nq={JUMP_SECRET}：外显信息跳转jumpsecret (第三方创建回调或者推送外显信息返回)

注：jump_secret在跳转链接返回时，会由平台侧统一做url encode，接入方通过创建回调返回时，无需做url编码

例子：JUMP_SECRET 为：guild_open_id=111&channel_open_id=aaa&business_id=333 第三方可从_nq 参数中解析获取自己需要的信息，参数获取方式参考onload 函数

# 创建、删除回调

回调接口 QQ 频道后端会给第三方携带签名，第三方可根据签名校验请求的合法性。

# 请求通用签名算法

假设目前有如下参数：

参数	类型	值	说明
appid	uint32	2222222	小程序 AppID
ts	uint32	1465185768	请求时间
nonce	uint32	562341234	随机正整数

# 对参数排序

首先对所有请求参数按参数名的字典序（ ASCII 码）升序排序

注意：

只按参数名进行排序，参数值保持对应即可，不参与比大小；
按 ASCII 码比大小，如 InstanceIds.2 要排在 InstanceIds.12 后面，不是按字母表，也不是按数值。

用户可以借助编程语言中的相关排序函数来实现这一功能，如 php 中的 ksort 函数。

上述示例参数的排序结果如下：

'appid' : 2222222
'nonce' : 562341234,
'ts' : 1465185768

1
2
3

# 拼接请求字符串

此步骤生成请求字符串。将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式。

注意：“参数名称“和“参数值”为原始值而非 url 编码后的值。

然后将格式化后的各个参数用&拼接在一起。

最终生成的请求字符串为:

appid=2222222&nonce=562341234&ts=1465185768

# 拼接签名原文

此步骤生成签名原文字符串。签名原文字符串由以下几个参数构成: 请求方法: 支持 POST 和 GET 方式，样例使用 POST 请求，注意方法为全大写。

请求主机: 根据实际请求的域名填写

接口域名：app.qun.qq.com

请求路径：/robotapi/msg_reply/v2

请求字符串: 即上一步生成的请求字符串

请求 body: post 请求的时候，发出的包体原文（如果是上传文件等操作，则不需要拼接 body）

签名原文串的拼接规则为:

请求方法 + 请求域名 + 请求路径 + ? + 请求字符串 + 请求body

示例的拼接结果为：

POSTapp.qun.qq.com/robotapi/msg_reply/v2?appid=2222222&nonce=562341234&ts=1465185768&{"xxxx": 123}

# 生成签名串

此步骤生成签名串。使用 sha1算法对上一步中获得的签名原文字符串进行签名.

具体代码如下，以 PHP 语言为例:

$appkey = 'fakeAppkey';
$srcStr = 'POSTapp.qun.qq.com/robotapi/msg_reply/v2?appid=2222222&nonce=562341234&ts=1465185768&{"xxxx": 123}';
$signStr = base64_encode(hash_hmac('sha256', $srcStr, $appkey, true));
echo $signStr;

1
2
3
4

最终得到的签名串为:

whXBY/0lXFDtYGj0FvTTjem0tlw=

使用其它程序设计语言开发时，可用上面示例中的原文进行签名验证，得到的签名串与例子中的一致即可。

注意：需要小程序的appSecret提供给 QQ 频道配置，用于计算签名

jump_secret 作为频道跳转链接的占位符参数
创建回调支持 http（北极星地址或 http 请求链接）
Method：POST
编码方式：json
回调例子：例如：
- 创建回调：http://xxx.xxx.xxx/group_pro/create_channel_callback/v2?appid=xxx&ts=xxx&nonce=xxx&sign=xxxx；
  
  appid: 小程序的 AppID
  
  ts:时间戳
  
  nonce：随机数
  
  sign:签名串
- 删除回调：http://xxx.xxx.xxx/group_pro/delete_channel_callback/v2?appid=xxx&ts=xxx&nonce=xxx&sign=xxxx

# 创建回调请求体

参数名	类型	备注
event_type	number	1-创建事件；2-删除事件；
event_info	EventInfo	事件信息

# EventInfo

参数名	类型	备注
guild_open_id	string	频道 openID
channel_open_id	string	子频道 openID

# 创建回调返回体

参数名	类型	备注
code	number	错误码， 0 - 成功
err_msg	string	错误信息
response	EventResponse

# EventResponse

参数名	类型	备注
jump_secret	string	跳转至小程序时会携带，获取方法参考应用子频道跳转连接

# 删除回调返回体

参数名	类型	备注
code	number	错误码， 0 - 成功
err_msg	string	错误信息

# 外显信息推送

注：外显信息需要在子频道创建成功之后才可推送, 外显的跳转链接参考应用子频道跳转链接。

# sendMessageToChannel

本接口应在后端服务器调用，详细说明参见后端 API。

该接口支持第三方小程序开发者通过该 API 推送频道外显信息。

# 请求地址

POST https://api.q.qq.com/api/qqchannel/send_request

# 请求参数

属性	类型	默认值	必填	说明
access_token	string		是	小程序的 access_token
body	string		是	base64Encode(ReqBody)，即对 ReqBody 进行 base64 编码

注意：由于设计不当，当前接口的 body 中某些结构需要使用 base64 编码成字符串而非常规 json 形式，该情况会在下个版本的中进行改进，即统一成常规 POST 请求所使用的 json 请求体描述方式。

# ReqBody

参数名	类型	是否必填	备注
appid	uint64	必填	小程序的 AppID
channel_presence_datas	ChannelPresenceData[]	必填	外显信息列表，是个数组

# ChannelPresenceData

参数名	类型	是否必填	备注
show_scope	ShowScope	必填	外显信息展示范围：指定频道、指定子频道
template_id	int32	必填	选择的模板类型：目前支持 `1`
bytes_channel_presence_data	string	必填	base64Encode(ChannelPresenceTemplate1)，即对 ChannelPresenceTemplate1 进行 base64 编码
deadline	int64	非必填	Unix 过期时间戳，秒级；为 0 时不过期
description	string	非必填	应用子频道灰色文案

# ShowScope

注：如果不填写 channel_open_id，则指定频道内的该类型的应用子频道外显相同

参数名	类型	是否必填	备注
guild_open_id	string	必填	频道 openID
channel_open_id	string	非必填	如果填写子频道 openID，则 guild_open_id 必传

# bytes_channel_presence_data 的模板列表

# 模板 1

参数名	类型	备注
channel_presence_items	ChannelPresenceItemForTemplate1[]	模板 1 参数列表

# ChannelPresenceItemForTemplate1

参数名	类型	备注
channel_presence_text	string	外显文案
jump_secret	string	外显信息跳转参数，会原样放到小程序跳转的_nq 参数

# 返回值

# Object

返回的 JSON 数据包

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息

errcode 的合法值

值	说明
0	请求成功
30001	请求体 JSON 格式错误
30002	access_token 与小程序不对应
30003	Body 错误，请按照规则检查传递的 body
30004	后台接口错误，请联系 QQ 小程序客服

# 请求体示例

{
  "access_token": "xxxxxx",
  "body": base64Encode({
    "appid": "xxxxxx",
    "channel_presence_datas": [
      {
        "show_scope": {
          "guild_open_id": "xxxxxx",
          "channel_open_id": "xxxxxx"
        },
        "template_id": 1,
        "bytes_channel_presence_data": base64Encode({
          "channel_presence_items": [
            {
              "channel_presence_text": "xxxxxx",
              "jump_secret": "xxxxxx"
            }
          ]
        }),
        "deadline": 1650187626,
        "description": "xxxxxx"
      }
    ]
  })
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

注意：示例中base64Encode意为对括号中的json数据进行base64编码，整体结果是个string

# 返回数据示例

正常返回

{ "errcode": 0, "errmsg": "" }

错误时返回

{ "errcode": 30002, "errmsg": "access_token invalid" }

← 订阅消息-后端API