feat: 更新部分接口功能描述

tencent-connect · Dec 20, 2023 · 713b319 · 713b319
1 parent a2a8c47
commit 713b319
Show file tree

Hide file tree

Showing 12 changed files with 488 additions and 84 deletions.
diff --git a/docs/develop/api-v2/config.js b/docs/develop/api-v2/config.js
@@ -39,7 +39,17 @@ module.exports = {
               "dev-prepare/interface-framework/event-emit.md"
             ]
           },
-          "dev-prepare/unique-id.md"
+          "dev-prepare/unique-id.md",
+          {
+            "title": "错误与调试",
+            "collapsable": false,
+            "sidebarDepth": 1,
+            "path": "/develop/api-v2/dev-prepare/error-trace/",
+            "children": [
+              "dev-prepare/error-trace/openapi.md",
+              "dev-prepare/error-trace/websocket.md"
+            ]
+          },
         ]
       },
       {

diff --git a/docs/develop/api-v2/dev-prepare/error-trace/README.md b/docs/develop/api-v2/dev-prepare/error-trace/README.md
@@ -0,0 +1,9 @@
+# 错误与调试
+
+## 错误码
+
+## 有关 traceID
+
+在 openapi 的返回 http 头上，有一个 `X-Tps-trace-ID` 自定义头部，是平台的链路追踪 ID，如果开发者有无法自己定位的问题，需要找平台协助的时候，可以提取这个 ID，提交给平台方。
+
+方便查询相关日志。
diff --git a/docs/develop/api-v2/dev-prepare/error-trace/openapi.md b/docs/develop/api-v2/dev-prepare/error-trace/openapi.md
diff --git a/docs/develop/api-v2/dev-prepare/error-trace/websocket.md b/docs/develop/api-v2/dev-prepare/error-trace/websocket.md
@@ -0,0 +1,26 @@
+# websocket 
+
+### 错误码 code
+| 值              | 含义                                   | 是否可以重试 RESUME | 是否可以重试 IDENTIFY |
+| :-------------- | :------------------------------------- | :--- | :--- |
+| 4001 | 无效的 opcode | 否 | 否 |
+| 4002 | 无效的 payload | 否 | 否 |
+| 4007 | seq 错误 | 否 | **是** |
+| 4006 | 无效的 session id，无法继续 resume，请 identify | 否 | **是** |
+| 4008 | 发送 payload 过快，请重新连接，并遵守连接后返回的频控信息 | **是** | **是** |
+| 4009 | 连接过期，请重连并执行 resume 进行重新连接 | **是** | **是** |
+| 4010 | 无效的 shard | 否 | 否 |
+| 4011 | 连接需要处理的 guild 过多，请进行合理的分片 | 否 | 否 |
+| 4012 | 无效的 version | 否 | 否 |
+| 4013 | 无效的 intent | 否 | 否 |
+| 4014 | intent 无权限 | 否 | 否 |
+| 4014 | intent 无权限 | 否 | 否 |
+| 4900~4913| 内部错误，请重连 | 否 | **是** |
+| 4914| 机器人已下架,只允许连接沙箱环境,请断开连接,检验当前连接环境 | 否 | 否 |
+| 4915| 机器人已封禁,不允许连接,请断开连接,申请解封后再连接 | 否 | 否 |
+
+### 针对 websocket 错误码的简单处理逻辑
+
+- 4009 可以重新发起 resume
+- 4914，4915 不可以连接，请联系官方解封
+- 其他错误，请重新发起 identify
diff --git a/docs/develop/api-v2/dev-prepare/interface-framework/api-use.md b/docs/develop/api-v2/dev-prepare/interface-framework/api-use.md
@@ -4,7 +4,7 @@
 <!-- > QQ BOT 服务端开放的 openapi 接口，均使用 https 方式进行调用，通过  `access token` 机制实现对 openapi 接口调用的鉴权。 -->
 
 ::: tip 说明
-`QQ BOT` 服务端开放的 `openapi` 接口，均使用 `https` 方式进行调用，通过  `access token` 机制实现对 openapi 接口调用的鉴权。
+`QQ 机器人` 服务端开放的 `openapi` 接口，均使用 `https` 方式进行调用，通过  `AccessToken` 机制实现对 `openapi` 接口调用的鉴权。
 :::
 
 ## 获取调用凭证
@@ -90,16 +90,17 @@ https://api.sgroup.qq.com
 | 名称 | 类型 | 必填 | 描述 |
 | --- | --- | --- | --- |
 | Authorization | string | 是 | 格式值："QQBot ACCESS_TOKEN" |
-| X-Union-Appid | string | 是 | 格式值："BOT_APPID", 机器人 appid |
+| X-Union-Appid | string | 是 | 格式值："BOT_APPID", 机器人 AppID |
 
 **示例**
 ```json
-'headers'': {
-  'Authorization': "QQBot {ACCESS_TOKEN}",
-  'X-Union-Appid': "{BOT_APPID}",
+{
+  "headers": {
+    "Authorization": "QQBot {ACCESS_TOKEN}",
+    "X-Union-Appid": "{BOT_APPID}",
+  }
 }
 ```
 
 <!-- ## 调用权限错误码
-
 与  `access token` 权限有关的错误码。 -->
diff --git a/docs/develop/api-v2/server-inter/message/post_messages.md b/docs/develop/api-v2/server-inter/message/post_messages.md
@@ -2,9 +2,7 @@
 
 ### 接口
 
-```http
-POST /channels/{channel_id}/messages
-```
+`POST /channels/{channel_id}/messages`
 
 ### 功能描述
 
@@ -17,32 +15,51 @@ POST /channels/{channel_id}/messages
 - 不论主动消息还是被动消息，在一个子频道中，每 `1s` 只能发送 `5` 条消息。
 - 被动回复消息有效期为 `5` 分钟。超时会报错。
 - **发送消息接口要求机器人接口需要连接到 websocket 上保持在线状态**
-- 有关主动消息审核，可以通过 [Intents](../../dev-prepare/interface-framework/event-emit.md#事件类型Intents) 中审核事件 MESSAGE_AUDIT 返回 [MessageAudited](./template/model.md#messageaudited) 对象获取结果。
+- 有关主动消息审核，可以通过 [Intents](../../dev-prepare/interface-framework/event-emit.md#事件订阅Intents) 中审核事件 MESSAGE_AUDIT 返回 [MessageAudited](./template/model.md#messageaudited) 对象获取结果。
 
 ### Content-Type
 
-```http
-application/json
-```
+- 请求支持 `application/json` 和 `multipart/form-data` 两种。对于类型为 `multipart/form-data` 的请求，当字段类型为对象或数组时需要将字段序列化为 JSON 字符串后进行调用，可参考下文的[示例](#form-data-格式示例)。
+- 回包统一使用 `application/json`
 
-### 参数
+### 通用参数
 
-| 字段名             | 类型                        | 描述                                                          |
-|-------------------|-----------------------------------------------|--------------------------------------------|
-| content | string | 选填，消息内容，文本内容，支持[内嵌格式](message_format.md) |
-| embed | [MessageEmbed](./template/model.md#messageembed)| 选填，embed 消息，一种特殊的 ark，详情参考[Embed消息](../../server-inter/message/type/message-type.md#Embed) |
-| ark | [MessageArk](./template/model.md#messageark) ark消息对象 | 选填，ark 消息 |
+| 字段名             | 类型                        | 描述                                             |
+| ----------------- | -------------------------- |------------------------------------------------- |
+| content           | string                     | 选填，消息内容，文本内容，支持[内嵌格式](message_format.md) |
+| embed             | [MessageEmbed](./template/model.md#messageembed) | 选填，embed 消息，一种特殊的 ark，详情参考[Embed消息](../../server-inter/message/type/embed.md) |
+| ark               | [MessageArk](./template/model.md#messageark) ark消息对象  | 选填，ark 消息 |
 | message_reference | [MessageReference](./template/model.md#messagereference) 引用消息对象 | 选填，引用消息 |
-| image | string | 选填，图片url地址，平台会转存该图片，用于下发图片消息 |
-| msg_id | string | 选填，要回复的消息id([Message](./template/model.md#message).id), 在 [AT_CREATE_MESSAGE](message.md) 事件中获取。 |
-| markdown          | [MessageMarkdown](./template/model.md#messagemarkdown) markdown 消息对象 | 选填，markdown 息    |
+| image             | string                     | 选填，图片url地址，平台会转存该图片，用于下发图片消息 |
+| msg_id            | string                     | 选填，要回复的消息id([Message](./template/model.md#message).id), 在 [AT_CREATE_MESSAGE](message.md) 事件中获取。 |
+| event_id          | string                     | 选填，要回复的事件id, 在各事件对象中获取。 |
+| markdown          | [MessageMarkdown](./template/model.md#messagemarkdown) markdown 消息对象 | 选填，markdown 消息 |
+
+### `multipart/form-data` 专有参数
+
+| 字段名     | 类型 | 描述                                                     |
+| ---------- | ---- | -------------------------------------------------------- |
+| file_image | file | 图片文件。form-data 支持直接通过文件上传的方式发送图片。 |
 
-**content, embed, ark, image, markdown 至少需要有一个字段，否则无法下发消息。**
+**content, embed, ark, image/file_image, markdown 至少需要有一个字段，否则无法下发消息。**
 
 #### 主动消息与被动消息
 
-- 主动消息：发送消息时，未填充 `msg_id` 字段的消息。
-- 被动消息：发送消息时，填充了 `msg_id` 字段的消息。接口使用此 `msg_id` 拉取用户的消息，同时判断用户消息的发送时间，如果超过被动消息回复时效，将会不允许发送该消息。
+- 主动消息：发送消息时，未填充 `msg_id/event_id` 字段的消息。
+- 被动消息：发送消息时，填充了 `msg_id/event_id` 字段的消息。`msg_id` 和 `event_id` 两个字段任意填一个即为被动消息。接口使用此 `msg_id/event_id` 拉取用户的消息或事件，同时判断用户消息或事件的发送时间，如果超过被动消息回复时效，将会不允许发送该消息。
+- 目前支持被动回复的事件类型有:
+	GUILD_MEMBER_ADD
+	GUILD_MEMBER_UPDATE
+	GUILD_MEMBER_REMOVE
+	MESSAGE_REACTION_ADD
+	MESSAGE_REACTION_REMOVE
+	FORUM_THREAD_CREATE
+	FORUM_THREAD_UPDATE
+	FORUM_THREAD_DELETE
+	FORUM_POST_CREATE
+	FORUM_POST_DELETE
+	FORUM_REPLY_CREATE
+	FORUM_REPLY_DELETE
 
 ### 返回
 
@@ -66,7 +83,7 @@ application/json
 }
 ```
 
-### 示例
+### JSON 格式示例
 
 请求数据包
 
@@ -100,3 +117,34 @@ application/json
   "flags": 0
 }
 ```
+
+### form-data 格式示例
+
+请求数据包
+
+| 字段名  | 值                                                                         |
+| ------- | -------------------------------------------------------------------------- |
+| content | <@!1234>hello world                                                        |
+| ark     | \{"ark":\{"template_id":1,"kv":\[\{"key":"#DESC#","value":"机器人订阅消息"\}\]\}\} |
+
+```json
+{
+  "id": "xxxxxx",
+  "channel_id": "xxxxxx",
+  "guild_id": "xxxxxx",
+  "content": "<@!1234>hello world",
+  "timestamp": "2021-05-13T14:45:45+08:00",
+  "tts": false,
+  "mention_everyone": false,
+  "author": {
+    "id": "xxxxxx",
+    "username": "abc",
+    "avatar": "",
+    "bot": true
+  },
+  "embeds": [{}],
+  "pinned": false,
+  "type": 0,
+  "flags": 0
+}
+```
diff --git a/docs/develop/api-v2/server-inter/message/send-receive/rich-media.md b/docs/develop/api-v2/server-inter/message/send-receive/rich-media.md
@@ -24,10 +24,12 @@
     <td>HTTP Method</td>
     <td>POST</td>
 	</tr>
-	<!-- <tr>
+	<!-- 
+	<tr>
     <td>接口频率限制</td>
     <td></td>
-	</tr> -->
+	</tr> 
+	-->
 </table>
 
 - **路径参数**

diff --git a/docs/develop/api-v2/server-inter/message/send-receive/send.md b/docs/develop/api-v2/server-inter/message/send-receive/send.md
@@ -34,6 +34,9 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
   <!-- - 私信场景下，被动消息没有条数限制。 -->
   - 被动回复消息有效期为 `5 分钟`，超时会发送失败。
 
+发动的消息内容包含 URL 的说明：
+
+如开发者需要在消息内容发送含有 url 信息的消息，请现在 q.qq.com 后台-开发设置-消息URL配置 预先配置，否则会发送失败。
 
 ## 单聊
 
@@ -74,7 +77,7 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
 | **属性** | **类型** | **必填** | **说明** |
 | --- | --- | --- | --- |
 | content | string | 否 | 文本内容 |
-| msg_type | int | 是 | 消息类型：0 是文本，1 图文混排 ，2 是 markdown， 3 ark，4 embed，7 media 富媒体 |
+| msg_type | int | 是 | 消息类型：0 是文本，2 是 markdown， 3 ark，4 embed，7 media 富媒体 |
 | markdown | object | 否 | 格式参考"消息类型=\>markdown=\>数据结构与协议" |
 | keyboard | object | 否 | 格式参考"消息交互=\>消息按钮=\>数据结构与协" |
 | ark | object | 否 | 格式参考"消息类型=\>ark=\>数据结构与协议" |
@@ -145,7 +148,7 @@ QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动
 | **属性** | **类型** | **必填** | **说明** |
 | --- | --- | --- | --- |
 | content | string | 是 | 文本内容 |
-| msg_type | int | 是 | 消息类型： 0 文本，1 图文混排，2 是 markdown，3 ark 消息，4 embed，7 media 富媒体 |
+| msg_type | int | 是 | 消息类型： 0 文本，2 是 markdown，3 ark 消息，4 embed，7 media 富媒体 |
 | markdown | object | 否 | 格式参考"消息类型=\>markdown=\>数据结构与协议" |
 | keyboard | object | 否 | 格式参考"消息交互=\>消息按钮=\>数据结构与协" |
 | media | object | 否 | {file_info: ""} 数据来源"消息收发=\>富媒体消息" |

diff --git a/docs/develop/api-v2/server-inter/message/trans/msg-btn.md b/docs/develop/api-v2/server-inter/message/trans/msg-btn.md
@@ -37,27 +37,27 @@
 
 ## 数据结构与协议
 
-消息发送接口 keyboard 字段值是一个 json object，rows 数组表示每一行按钮
+消息发送接口 keyboard 字段值是一个 Json Object {}，rows 数组的每个元素表示每一行按钮
 
-每个 button 是一个 json object，具体字段如下：
+每个 button 是一个 Json Object，具体字段如下：
 
 | **属性** | **类型** | **必填** | **说明** |
 | --- | --- | --- | --- |
 | id | string | 否 | 按钮ID：在一个keyboard消息内设置唯一 |
 | render_data.label | string | 是 | 按钮上的文字 |
 | render_data.visited_label | string | 是 | 点击后按钮的上文字 |
 | render_data.style | int | 是 | 按钮样式：0 灰色线框，1 蓝色线框 |
-| action.type | int | 是 | 0 跳转按钮：http 或 小程序 客户端识别 scheme, data字段为链接1 回调按钮：回调后台接口, data 传给后台2 指令按钮：自动在输入框插入 @bot data |
-| action.permisson.type | int | 是 | 0 指定用户可操作1 仅管理者可操作2 所有人可操作3 指定身份组可操作（仅频道可用） |
-| action.permisson.specify_role_ids | array | 否 | 有权限的身份组id的列表（仅频道可用） |
-| action.permisson.specify_user_ids | array | 否 | 有权限的用户id的列表 |
-| data | string | 是 | 操作相关的数据 |
-| at_bot_show_channel_list | bool | 否 | 指令按钮可用，弹出子频道选择器，默认 false（已弃用） |
-| reply | bool | 否 | 指令按钮可用，指令是否带引用回复本消息，默认 false支持版本 8983 |
-| enter | bool | 否 | 指令按钮可用，点击按钮后直接自动发送 data，默认 false。支持版本 8983 |
-| anchor | bool | 否 | 指令按钮可用，自动锚点到选图器，默认 false，设置 ture 后会忽略 enter 配置。支持版本 8983 |
-| click_limit | int | 否 | 可操作点击的次数，默认不限 |
-| unsupport_tips | string | 是 | 客户端不支持本action的时候，弹出的toast文案 |
+| action.type | int | 是 | 设置 0 跳转按钮：http 或 小程序 客户端识别 scheme，设置 1 回调按钮：回调后台接口, data 传给后台，设置 2 指令按钮：自动在输入框插入 @bot data |
+| action.permisson.type | int | 是 | 0 指定用户可操作，1 仅管理者可操作，2 所有人可操作，3 指定身份组可操作（仅频道可用） |
+| action.permisson.specify_user_ids | array | 否 | 有权限的用户 id 的列表 |
+| action.permisson.specify_role_ids | array | 否 | 有权限的身份组 id 的列表（仅频道可用） |
+| action.data | string | 是 | 操作相关的数据 |
+| action.reply | bool | 否 | 指令按钮可用，指令是否带引用回复本消息，默认 false。支持版本 8983 |
+| action.enter | bool | 否 | 指令按钮可用，点击按钮后直接自动发送 data，默认 false。支持版本 8983 |
+| action.anchor | bool | 否 | 指令按钮可用，自动锚点到选图器，默认 false，设置 ture 后会忽略 enter 配置。支持版本 8983 |
+| action.click_limit | int | 否 |【已弃用】可操作点击的次数，默认不限 |
+| action.at_bot_show_channel_list | bool | 否 |【已弃用】指令按钮可用，弹出子频道选择器，默认 false |
+| action.unsupport_tips | string | 是 | 客户端不支持本action的时候，弹出的toast文案 |
 
 示例
 ```json
@@ -174,17 +174,20 @@
 | **属性** | **类型** | **说明** |
 | --- | --- | --- |
 | id | string | 平台方事件 ID，可以用于被动消息发送 |
-| type | int | <font color=red>按钮事件固定是 11</font> |
-| chat_type | int | 消息内容 |
-| timestamp | string | 消息生产时间 |
-| guild_id | string | 频道的 openid |
-| channel_id | string | 文字子频道的 openid |
-| group_open_id | string | 群聊的 openid |
-| chat_type | int | 目前只有群和单聊有该字段，1 群聊，2 单聊，后续加入 3 频道 |
-| data.resoloved.button_data | string | 操作按钮的data字段值【在发送按钮时规划】 |
-| data.resoloved.button_id | string | 操作按钮的id字段值【在发送按钮时规划】 |
-| data.resoloved.user_id | string | 操作的用户 openid |
-| data.resoloved.message_id | string | 操作的消息id |
+| type | int | 消息按钮： 11，单聊快捷菜单：12 |
+| scene | string | 事件发生的场景：c2c、group、guild |
+| chat_type | int | 0 频道场景，1 群聊场景，2 单聊场景 |
+| timestamp | string | 触发时间 RFC 3339 格式 |
+| guild_id | string | 频道的 openid ，仅在频道场景提供该字段 |
+| channel_id | string | 文字子频道的 openid，仅在频道场景提供该字段 |
+| user_openid | string | 单聊单聊按钮触发x，的用户 openid，仅在单聊场景提供该字段 |
+| group_openid | string | 群的 openid，仅在群聊场景提供该字段 |
+| group_member_openid | string | 按钮触发用户，群聊的群成员 openid，仅在群聊场景提供该字段 |
+| data.resoloved.button_data | string | 操作按钮的 data 字段值（在发送消息按钮时设置） |
+| data.resoloved.button_id | string | 操作按钮的 id 字段值（在发送消息按钮时设置） |
+| data.resoloved.user_id | string | 操作的用户 userid，仅频道场景提供该字段 |
+| data.resoloved.feature_id | string | 操作按钮的 id 字段值，仅自定义菜单提供该字段（在管理端设置） |
+| data.resoloved.message_id | string | 操作的消息id，目前仅频道场景提供该字段 |
 | version | int | 默认 1 |
 | application_id | string | 机器人的 appid |