Skip to content

Commit 713b319

Browse files
mengjie0320mengjie0320
committed
feat: 更新部分接口功能描述
1 parent a2a8c47 commit 713b319

File tree

12 files changed

+488
-84
lines changed

12 files changed

+488
-84
lines changed

‎docs/develop/api-v2/config.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,17 @@ module.exports = {
3939
"dev-prepare/interface-framework/event-emit.md"
4040
]
4141
},
42-
"dev-prepare/unique-id.md"
42+
"dev-prepare/unique-id.md",
43+
{
44+
"title": "错误与调试",
45+
"collapsable": false,
46+
"sidebarDepth": 1,
47+
"path": "/develop/api-v2/dev-prepare/error-trace/",
48+
"children": [
49+
"dev-prepare/error-trace/openapi.md",
50+
"dev-prepare/error-trace/websocket.md"
51+
]
52+
},
4353
]
4454
},
4555
{

‎docs/develop/api-v2/dev-prepare/error-trace/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# 错误与调试
2+
3+
## 错误码
4+
5+
## 有关 traceID
6+
7+
在 openapi 的返回 http 头上，有一个 `X-Tps-trace-ID` 自定义头部，是平台的链路追踪 ID，如果开发者有无法自己定位的问题，需要找平台协助的时候，可以提取这个 ID，提交给平台方。
8+
9+
方便查询相关日志。

‎docs/develop/api-v2/dev-prepare/error-trace/openapi.md‎

Lines changed: 279 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/develop/api-v2/dev-prepare/error-trace/websocket.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# websocket
2+
3+
### 错误码 code
4+
| 值 | 含义 | 是否可以重试 RESUME | 是否可以重试 IDENTIFY |
5+
| :-------------- | :------------------------------------- | :--- | :--- |
6+
| 4001 | 无效的 opcode | 否 | 否 |
7+
| 4002 | 无效的 payload | 否 | 否 |
8+
| 4007 | seq 错误 | 否 | **是** |
9+
| 4006 | 无效的 session id，无法继续 resume，请 identify | 否 | **是** |
10+
| 4008 | 发送 payload 过快，请重新连接，并遵守连接后返回的频控信息 | **是** | **是** |
11+
| 4009 | 连接过期，请重连并执行 resume 进行重新连接 | **是** | **是** |
12+
| 4010 | 无效的 shard | 否 | 否 |
13+
| 4011 | 连接需要处理的 guild 过多，请进行合理的分片 | 否 | 否 |
14+
| 4012 | 无效的 version | 否 | 否 |
15+
| 4013 | 无效的 intent | 否 | 否 |
16+
| 4014 | intent 无权限 | 否 | 否 |
17+
| 4014 | intent 无权限 | 否 | 否 |
18+
| 4900~4913| 内部错误，请重连 | 否 | **是** |
19+
| 4914| 机器人已下架,只允许连接沙箱环境,请断开连接,检验当前连接环境 | 否 | 否 |
20+
| 4915| 机器人已封禁,不允许连接,请断开连接,申请解封后再连接 | 否 | 否 |
21+
22+
### 针对 websocket 错误码的简单处理逻辑
23+
24+
- 4009 可以重新发起 resume
25+
- 4914，4915 不可以连接，请联系官方解封
26+
- 其他错误，请重新发起 identify

‎docs/develop/api-v2/dev-prepare/interface-framework/api-use.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<!-- > QQ BOT 服务端开放的 openapi 接口，均使用 https 方式进行调用，通过 `access token` 机制实现对 openapi 接口调用的鉴权。 -->
55

66
::: tip 说明
7-
`QQ BOT` 服务端开放的 `openapi` 接口，均使用 `https` 方式进行调用，通过 `access token` 机制实现对 openapi 接口调用的鉴权。
7+
`QQ 机器人` 服务端开放的 `openapi` 接口，均使用 `https` 方式进行调用，通过 `AccessToken` 机制实现对 `openapi` 接口调用的鉴权。
88
:::
99

1010
## 获取调用凭证
@@ -90,16 +90,17 @@ https://api.sgroup.qq.com
9090
| 名称 | 类型 | 必填 | 描述 |
9191
| --- | --- | --- | --- |
9292
| Authorization | string | 是 | 格式值："QQBot ACCESS_TOKEN" |
93-
| X-Union-Appid | string | 是 | 格式值："BOT_APPID", 机器人 appid |
93+
| X-Union-Appid | string | 是 | 格式值："BOT_APPID", 机器人 AppID |
9494

9595
**示例**
9696
```json
97-
'headers'': {
98-
'Authorization': "QQBot {ACCESS_TOKEN}",
99-
'X-Union-Appid': "{BOT_APPID}",
97+
{
98+
"headers": {
99+
"Authorization": "QQBot {ACCESS_TOKEN}",
100+
"X-Union-Appid": "{BOT_APPID}",
101+
}
100102
}
101103
```
102104

103105
<!-- ## 调用权限错误码
104-
105106
与 `access token` 权限有关的错误码。 -->

‎docs/develop/api-v2/server-inter/message/post_messages.md‎

Lines changed: 68 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22

33
### 接口
44

5-
```http
6-
POST /channels/{channel_id}/messages
7-
```
5+
`POST /channels/{channel_id}/messages`
86

97
### 功能描述
108

@@ -17,32 +15,51 @@ POST /channels/{channel_id}/messages
1715
- 不论主动消息还是被动消息，在一个子频道中，每 `1s` 只能发送 `5` 条消息。
1816
- 被动回复消息有效期为 `5` 分钟。超时会报错。
1917
- **发送消息接口要求机器人接口需要连接到 websocket 上保持在线状态**
20-
- 有关主动消息审核，可以通过 [Intents](../../dev-prepare/interface-framework/event-emit.md#事件类型Intents) 中审核事件 MESSAGE_AUDIT 返回 [MessageAudited](./template/model.md#messageaudited) 对象获取结果。
18+
- 有关主动消息审核，可以通过 [Intents](../../dev-prepare/interface-framework/event-emit.md#事件订阅Intents) 中审核事件 MESSAGE_AUDIT 返回 [MessageAudited](./template/model.md#messageaudited) 对象获取结果。
2119

2220
### Content-Type
2321

24-
```http
25-
application/json
26-
```
22+
- 请求支持 `application/json` 和 `multipart/form-data` 两种。对于类型为 `multipart/form-data` 的请求，当字段类型为对象或数组时需要将字段序列化为 JSON 字符串后进行调用，可参考下文的[示例](#form-data-格式示例)。
23+
- 回包统一使用 `application/json`
2724

28-
### 参数
25+
### 通用参数
2926

30-
| 字段名 | 类型 | 描述 |
31-
|-------------------|-----------------------------------------------|--------------------------------------------|
32-
| content | string | 选填，消息内容，文本内容，支持[内嵌格式](message_format.md) |
33-
| embed | [MessageEmbed](./template/model.md#messageembed)| 选填，embed 消息，一种特殊的 ark，详情参考[Embed消息](../../server-inter/message/type/message-type.md#Embed) |
34-
| ark | [MessageArk](./template/model.md#messageark) ark消息对象 | 选填，ark 消息 |
27+
| 字段名 | 类型 | 描述 |
28+
| ----------------- | -------------------------- |------------------------------------------------- |
29+
| content | string | 选填，消息内容，文本内容，支持[内嵌格式](message_format.md) |
30+
| embed | [MessageEmbed](./template/model.md#messageembed) | 选填，embed 消息，一种特殊的 ark，详情参考[Embed消息](../../server-inter/message/type/embed.md) |
31+
| ark | [MessageArk](./template/model.md#messageark) ark消息对象 | 选填，ark 消息 |
3532
| message_reference | [MessageReference](./template/model.md#messagereference) 引用消息对象 | 选填，引用消息 |
36-
| image | string | 选填，图片url地址，平台会转存该图片，用于下发图片消息 |
37-
| msg_id | string | 选填，要回复的消息id([Message](./template/model.md#message).id), 在 [AT_CREATE_MESSAGE](message.md) 事件中获取。 |
38-
| markdown | [MessageMarkdown](./template/model.md#messagemarkdown) markdown 消息对象 | 选填，markdown 息 |
33+
| image | string | 选填，图片url地址，平台会转存该图片，用于下发图片消息 |
34+
| msg_id | string | 选填，要回复的消息id([Message](./template/model.md#message).id), 在 [AT_CREATE_MESSAGE](message.md) 事件中获取。 |
35+
| event_id | string | 选填，要回复的事件id, 在各事件对象中获取。 |
36+
| markdown | [MessageMarkdown](./template/model.md#messagemarkdown) markdown 消息对象 | 选填，markdown 消息 |
37+
38+
### `multipart/form-data` 专有参数
39+
40+
| 字段名 | 类型 | 描述 |
41+
| ---------- | ---- | -------------------------------------------------------- |
42+
| file_image | file | 图片文件。form-data 支持直接通过文件上传的方式发送图片。 |
3943

40-
**content, embed, ark, image, markdown 至少需要有一个字段，否则无法下发消息。**
44+
**content, embed, ark, image/file_image, markdown 至少需要有一个字段，否则无法下发消息。**
4145

4246
#### 主动消息与被动消息
4347

44-
- 主动消息：发送消息时，未填充 `msg_id` 字段的消息。
45-
- 被动消息：发送消息时，填充了 `msg_id` 字段的消息。接口使用此 `msg_id` 拉取用户的消息，同时判断用户消息的发送时间，如果超过被动消息回复时效，将会不允许发送该消息。
48+
- 主动消息：发送消息时，未填充 `msg_id/event_id` 字段的消息。
49+
- 被动消息：发送消息时，填充了 `msg_id/event_id` 字段的消息。`msg_id` 和 `event_id` 两个字段任意填一个即为被动消息。接口使用此 `msg_id/event_id` 拉取用户的消息或事件，同时判断用户消息或事件的发送时间，如果超过被动消息回复时效，将会不允许发送该消息。
50+
- 目前支持被动回复的事件类型有:
51+
GUILD_MEMBER_ADD
52+
GUILD_MEMBER_UPDATE
53+
GUILD_MEMBER_REMOVE
54+
MESSAGE_REACTION_ADD
55+
MESSAGE_REACTION_REMOVE
56+
FORUM_THREAD_CREATE
57+
FORUM_THREAD_UPDATE
58+
FORUM_THREAD_DELETE
59+
FORUM_POST_CREATE
60+
FORUM_POST_DELETE
61+
FORUM_REPLY_CREATE
62+
FORUM_REPLY_DELETE
4663

4764
### 返回
4865

@@ -66,7 +83,7 @@ application/json
6683
}
6784
```
6885

69-
### 示例
86+
### JSON 格式示例
7087

7188
请求数据包
7289

@@ -100,3 +117,34 @@ application/json
100117
"flags": 0
101118
}
102119
```
120+
121+
### form-data 格式示例
122+
123+
请求数据包
124+
125+
| 字段名 | 值 |
126+
| ------- | -------------------------------------------------------------------------- |
127+
| content | <@!1234>hello world |
128+
| ark | \{"ark":\{"template_id":1,"kv":\[\{"key":"#DESC#","value":"机器人订阅消息"\}\]\}\} |
129+
130+
```json
131+
{
132+
"id": "xxxxxx",
133+
"channel_id": "xxxxxx",
134+
"guild_id": "xxxxxx",
135+
"content": "<@!1234>hello world",
136+
"timestamp": "2021-05-13T14:45:45+08:00",
137+
"tts": false,
138+
"mention_everyone": false,
139+
"author": {
140+
"id": "xxxxxx",
141+
"username": "abc",
142+
"avatar": "",
143+
"bot": true
144+
},
145+
"embeds": [{}],
146+
"pinned": false,
147+
"type": 0,
148+
"flags": 0
149+
}
150+
```

‎docs/develop/api-v2/server-inter/message/send-receive/rich-media.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,12 @@
2424
<td>HTTP Method</td>
2525
<td>POST</td>
2626
</tr>
27-
<!-- <tr>
27+
<!--
28+
<tr>
2829
<td>接口频率限制</td>
2930
<td></td>
30-
</tr> -->
31+
</tr>
32+
-->
3133
</table>
3234

3335
- **路径参数**

‎docs/develop/api-v2/server-inter/message/send-receive/send.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
3434
<!-- - 私信场景下，被动消息没有条数限制。 -->
3535
- 被动回复消息有效期为 `5 分钟`，超时会发送失败。
3636

37+
发动的消息内容包含 URL 的说明：
38+
39+
如开发者需要在消息内容发送含有 url 信息的消息，请现在 q.qq.com 后台-开发设置-消息URL配置 预先配置，否则会发送失败。
3740

3841
## 单聊
3942

@@ -74,7 +77,7 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
7477
| **属性** | **类型** | **必填** | **说明** |
7578
| --- | --- | --- | --- |
7679
| content | string | 否 | 文本内容 |
77-
| msg_type | int | 是 | 消息类型：0 是文本，1 图文混排 ，2 是 markdown， 3 ark，4 embed，7 media 富媒体 |
80+
| msg_type | int | 是 | 消息类型：0 是文本，2 是 markdown， 3 ark，4 embed，7 media 富媒体 |
7881
| markdown | object | 否 | 格式参考"消息类型=\>markdown=\>数据结构与协议" |
7982
| keyboard | object | 否 | 格式参考"消息交互=\>消息按钮=\>数据结构与协" |
8083
| ark | object | 否 | 格式参考"消息类型=\>ark=\>数据结构与协议" |
@@ -145,7 +148,7 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
145148
| **属性** | **类型** | **必填** | **说明** |
146149
| --- | --- | --- | --- |
147150
| content | string | 是 | 文本内容 |
148-
| msg_type | int | 是 | 消息类型： 0 文本，1 图文混排，2 是 markdown，3 ark 消息，4 embed，7 media 富媒体 |
151+
| msg_type | int | 是 | 消息类型： 0 文本，2 是 markdown，3 ark 消息，4 embed，7 media 富媒体 |
149152
| markdown | object | 否 | 格式参考"消息类型=\>markdown=\>数据结构与协议" |
150153
| keyboard | object | 否 | 格式参考"消息交互=\>消息按钮=\>数据结构与协" |
151154
| media | object | 否 | {file_info: ""} 数据来源"消息收发=\>富媒体消息" |

‎docs/develop/api-v2/server-inter/message/trans/msg-btn.md‎

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -37,27 +37,27 @@
3737

3838
## 数据结构与协议
3939

40-
消息发送接口 keyboard 字段值是一个 json object，rows 数组表示每一行按钮
40+
消息发送接口 keyboard 字段值是一个 Json Object {}，rows 数组的每个元素表示每一行按钮
4141

42-
每个 button 是一个 json object，具体字段如下：
42+
每个 button 是一个 Json Object，具体字段如下：
4343

4444
| **属性** | **类型** | **必填** | **说明** |
4545
| --- | --- | --- | --- |
4646
| id | string | 否 | 按钮ID：在一个keyboard消息内设置唯一 |
4747
| render_data.label | string | 是 | 按钮上的文字 |
4848
| render_data.visited_label | string | 是 | 点击后按钮的上文字 |
4949
| render_data.style | int | 是 | 按钮样式：0 灰色线框，1 蓝色线框 |
50-
| action.type | int | 是 | 0 跳转按钮：http 或 小程序 客户端识别 scheme, data字段为链接1 回调按钮：回调后台接口, data 传给后台2 指令按钮：自动在输入框插入 @bot data |
51-
| action.permisson.type | int | 是 | 0 指定用户可操作1 仅管理者可操作2 所有人可操作3 指定身份组可操作（仅频道可用） |
52-
| action.permisson.specify_role_ids | array | 否 | 有权限的身份组id的列表（仅频道可用） |
53-
| action.permisson.specify_user_ids | array | 否 | 有权限的用户id的列表 |
54-
| data | string | 是 | 操作相关的数据 |
55-
| at_bot_show_channel_list | bool | 否 | 指令按钮可用，弹出子频道选择器，默认 false（已弃用） |
56-
| reply | bool | 否 | 指令按钮可用，指令是否带引用回复本消息，默认 false支持版本 8983 |
57-
| enter | bool | 否 | 指令按钮可用，点击按钮后直接自动发送 data，默认 false。支持版本 8983 |
58-
| anchor | bool | 否 | 指令按钮可用，自动锚点到选图器，默认 false，设置 ture 后会忽略 enter 配置。支持版本 8983 |
59-
| click_limit | int | 否 | 可操作点击的次数，默认不限 |
60-
| unsupport_tips | string | 是 | 客户端不支持本action的时候，弹出的toast文案 |
50+
| action.type | int | 是 | 设置 0 跳转按钮：http 或 小程序 客户端识别 scheme，设置 1 回调按钮：回调后台接口, data 传给后台，设置 2 指令按钮：自动在输入框插入 @bot data |
51+
| action.permisson.type | int | 是 | 0 指定用户可操作，1 仅管理者可操作，2 所有人可操作，3 指定身份组可操作（仅频道可用） |
52+
| action.permisson.specify_user_ids | array | 否 | 有权限的用户 id 的列表 |
53+
| action.permisson.specify_role_ids | array | 否 | 有权限的身份组 id 的列表（仅频道可用） |
54+
| action.data | string | 是 | 操作相关的数据 |
55+
| action.reply | bool | 否 | 指令按钮可用，指令是否带引用回复本消息，默认 false。支持版本 8983 |
56+
| action.enter | bool | 否 | 指令按钮可用，点击按钮后直接自动发送 data，默认 false。支持版本 8983 |
57+
| action.anchor | bool | 否 | 指令按钮可用，自动锚点到选图器，默认 false，设置 ture 后会忽略 enter 配置。支持版本 8983 |
58+
| action.click_limit | int | 否 |【已弃用】可操作点击的次数，默认不限 |
59+
| action.at_bot_show_channel_list | bool | 否 |【已弃用】指令按钮可用，弹出子频道选择器，默认 false |
60+
| action.unsupport_tips | string | 是 | 客户端不支持本action的时候，弹出的toast文案 |
6161

6262
示例
6363
```json
@@ -174,17 +174,20 @@
174174
| **属性** | **类型** | **说明** |
175175
| --- | --- | --- |
176176
| id | string | 平台方事件 ID，可以用于被动消息发送 |
177-
| type | int | <font color=red>按钮事件固定是 11</font> |
178-
| chat_type | int | 消息内容 |
179-
| timestamp | string | 消息生产时间 |
180-
| guild_id | string | 频道的 openid |
181-
| channel_id | string | 文字子频道的 openid |
182-
| group_open_id | string | 群聊的 openid |
183-
| chat_type | int | 目前只有群和单聊有该字段，1 群聊，2 单聊，后续加入 3 频道 |
184-
| data.resoloved.button_data | string | 操作按钮的data字段值【在发送按钮时规划】 |
185-
| data.resoloved.button_id | string | 操作按钮的id字段值【在发送按钮时规划】 |
186-
| data.resoloved.user_id | string | 操作的用户 openid |
187-
| data.resoloved.message_id | string | 操作的消息id |
177+
| type | int | 消息按钮： 11，单聊快捷菜单：12 |
178+
| scene | string | 事件发生的场景：c2c、group、guild |
179+
| chat_type | int | 0 频道场景，1 群聊场景，2 单聊场景 |
180+
| timestamp | string | 触发时间 RFC 3339 格式 |
181+
| guild_id | string | 频道的 openid ，仅在频道场景提供该字段 |
182+
| channel_id | string | 文字子频道的 openid，仅在频道场景提供该字段 |
183+
| user_openid | string | 单聊单聊按钮触发x，的用户 openid，仅在单聊场景提供该字段 |
184+
| group_openid | string | 群的 openid，仅在群聊场景提供该字段 |
185+
| group_member_openid | string | 按钮触发用户，群聊的群成员 openid，仅在群聊场景提供该字段 |
186+
| data.resoloved.button_data | string | 操作按钮的 data 字段值（在发送消息按钮时设置） |
187+
| data.resoloved.button_id | string | 操作按钮的 id 字段值（在发送消息按钮时设置） |
188+
| data.resoloved.user_id | string | 操作的用户 userid，仅频道场景提供该字段 |
189+
| data.resoloved.feature_id | string | 操作按钮的 id 字段值，仅自定义菜单提供该字段（在管理端设置） |
190+
| data.resoloved.message_id | string | 操作的消息id，目前仅频道场景提供该字段 |
188191
| version | int | 默认 1 |
189192
| application_id | string | 机器人的 appid |
190193

0 commit comments

Comments
 (0)