Skip to content

Commit 38f515a

Browse files
pangxiaolipangxiaoli
committed
feat(node sdk): 补充群聊及私信相关文档
1 parent 7d9972e commit 38f515a

File tree

9 files changed

+250
-5
lines changed

9 files changed

+250
-5
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@ node_modules
22
dist/
33
package-lock.json
44
yarn.lock
5+
pnpm-lock.yaml
56
yarn-error.log
7+
.yarn
68

79
# General
810
.DS_Store

‎.yarnrc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
nodeLinker: node-modules

‎docs/develop/nodesdk/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,9 @@ ws.on('AUDIO_ACTION', (data) => {
156156
ws.on('PUBLIC_GUILD_MESSAGES', (data) => {
157157
console.log('[PUBLIC_GUILD_MESSAGES] 事件接收 :', data);
158158
});
159+
ws.on("GROUP_AND_C2C_EVENT", (data) => {
160+
console.log("[GROUP_AND_C2C_EVENT] 事件接收 :", data);
161+
});
159162
```
160163

161164
### ws 返回示例

‎docs/develop/nodesdk/config.js‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ module.exports = {
2525
{ title: '成员对象(Member)', path: 'model/member' },
2626
{ title: '频道身份组对象(Role)', path: 'model/role' },
2727
{ title: '消息对象(Message)', path: 'model/message' },
28-
{title: '消息按钮对象(InlineKeyboard)', path: 'model/inline_keyboard'},
28+
{ title: '消息按钮对象(InlineKeyboard)', path: 'model/inline_keyboard' },
2929
{ title: '私信对象(DMS)', path: 'model/dms' },
3030
{ title: '公告对象(Announce)', path: 'model/announce' },
3131
{ title: '精华消息对象(PinsMessage)', path: 'model/pins_message.md' },
@@ -94,7 +94,7 @@ module.exports = {
9494
],
9595
},
9696
{
97-
title: '消息 API',
97+
title: '频道消息 API',
9898
collapsable: false,
9999
sidebarDepth: 0,
100100
children: [
@@ -109,7 +109,7 @@ module.exports = {
109109
],
110110
},
111111
{
112-
title: '私信 API',
112+
title: '频道私信 API',
113113
collapsable: false,
114114
sidebarDepth: 0,
115115
children: ['dms/post_dms.md', 'dms/post_dms_messages.md'],
@@ -170,7 +170,13 @@ module.exports = {
170170
title: '接口权限 API',
171171
collapsable: false,
172172
sidebarDepth: 0,
173-
children: ['api_permissions/get_permissions','api_permissions/post_permission.md'],
173+
children: ['api_permissions/get_permissions', 'api_permissions/post_permission.md'],
174+
},
175+
{
176+
title: 'QQ 群和私聊 API',
177+
collapsable: false,
178+
sidebarDepth: 0,
179+
children: ['group_and_c2c/post_message', 'group_and_c2c/files.md', 'group_and_c2c/del_message'],
174180
},
175181
],
176182
},

‎docs/develop/nodesdk/group_and_c2c/del_message.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 撤回消息 <Badge text="v2.10.0" />
2+
3+
## 功能描述
4+
5+
用于撤回机器人发送给当前用户 openid 的消息 message_id，发送超出2分钟的消息不可撤回
6+
7+
## 使用示例
8+
9+
```js
10+
/** 单聊 */
11+
async function demo() {
12+
const res = await client.C2cAPI.delMessage(openid, message_id);
13+
}
14+
15+
/** 群聊 */
16+
async function demo() {
17+
const res = await client.GroupAPI.delMessage(group_openid, message_id);
18+
}
19+
```
20+
21+
## 参数说明
22+
23+
| 字段名 | 必填 | 类型 | 描述 |
24+
| ------- | ---- | -------------------------------------------------------------- | ---------------------------------------------------- |
25+
| openid | 是（单聊） | string | QQ 用户的 openid，可在各类事件中获得。 |
26+
| group_openid | 是（群聊） | string | 群号，可在各类事件中获得。|
27+
| message_id | 是 | string | 消息id |
28+
29+
30+
## 返回参数
31+
32+
成功返回 HTTP 状态码 200。

‎docs/develop/nodesdk/group_and_c2c/files.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# 发送富媒体消息 <Badge text="v2.10.0" />
2+
3+
## 功能描述
4+
5+
仅用于在QQ单聊和QQ群聊内，发送图片、视频、语音、文件的相关富媒体资源在消息收发的候使用。 本接口有以下两种使用方式：
6+
7+
- 当 `srv_send_msg = true` 时，消息会直接发送到目标端，占用 主动消息频次，超频会发送失败。
8+
9+
- 当 `srv_send_msg = false` 时，消息不会直接发送到目标端，返回的 file_info 字段数据，可使用在消息发送接口 `media` 字段中，`file_info` 有 过期时间 ，开发者需要自行维护有效期，过期需要重新获得新的 `file_info`，`file_info` 不受发送的目标端影响，一个 `file_info` 可复用发送到多个群或多个用户（注意：用 `GroupAPI` 上传的文件，仅能发到群聊内，用 `C2cAPI` 上传的文件，也仅能发送到单聊）。
10+
11+
推荐使用第 2 种方式
12+
13+
## 使用示例
14+
15+
- 单聊
16+
```js
17+
async function demo() {
18+
const res = await client.c2cApi.files('openid', {
19+
file_type: 1,
20+
url: '',
21+
srv_send_msg: false,
22+
})
23+
24+
const result = client.c2cApi.postMessage('openid', {
25+
msg_type: 7,
26+
media: {
27+
file_info: res.data.file_info,
28+
},
29+
msg_id: 'msg_id',
30+
event_id: 'event_id',
31+
})
32+
}
33+
```
34+
35+
- 群聊
36+
```js
37+
async function demo() {
38+
const res = await client.groupApi.files('group_openid', {
39+
file_type: 1,
40+
url: '',
41+
srv_send_msg: false,
42+
})
43+
44+
const result = client.groupApi.postMessage('group_openid', {
45+
msg_type: 7,
46+
media: {
47+
file_info: res.data.file_info,
48+
},
49+
msg_id: 'msg_id',
50+
event_id: 'event_id',
51+
})
52+
}
53+
```
54+
55+
## 参数说明
56+
57+
| 字段名 | 必填 | 类型 | 描述 |
58+
| ------- | ---- | -------------------------------------------------------------- | ---------------------------------------------------- |
59+
| openid | 是（单聊） | string | QQ 用户的 openid，可在各类事件中获得。 |
60+
| group_openid | 是（群聊） | string | 群号，可在各类事件中获得。|
61+
| TMedia | 是 | [TMedia](./post_message.md#tmedia) | 富媒体对象 |
62+
63+
64+
## 返回参数
65+
66+
| 字段 | 类型 | 说明 |
67+
|-----------|------------|----------------------------------------------------------------------|
68+
| `file_uuid` | `string` | 文件 ID |
69+
| `file_info` | `string` | 文件信息，用于发消息接口的 `media` 字段使用 |
70+
| `ttl` | `number` | 有效期，表示剩余多少秒到期，到期后 `file_info` 失效，等于 `0` 时表示可长期使用 |
71+
| `id` | `string` | 发送消息的唯一 ID，当 `srv_send_msg` 设置为 `true` 时返回 |
72+
73+
## 返回示例
74+
75+
```json
76+
{
77+
"file_uuid": "f3d2f5b7-7f3a-4d8a-9e2d-8e8d8e8e8e8e",
78+
"file_info": "",
79+
"ttl": 86400,
80+
"id": "id"
81+
}
82+
```

‎docs/develop/nodesdk/group_and_c2c/post_message.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# 发送消息 <Badge text="v2.10.0" />
2+
3+
## 功能描述
4+
5+
- 主动消息与被动消息说明： QQ 用户可以在 QQ 客户端主动设置是否接收机器人发送的主动消息，如果设置了关闭，主动消息一律发送失败。
6+
- 单聊
7+
- 主动消息每月 4 条，超额会发送失败。（例如：给相同用户每月最多发 4 条）
8+
- 被动消息（回复类）有效时间为 60 分钟，每个消息最多回复 5 次，超时或超频会发送（回复）失败；
9+
- 群聊
10+
- 主动消息每月 4 条，超额会发送失败。（例如：给相同群每月最多发 4 条）
11+
- 被动消息（回复类）有效时间为 5 分钟，每个消息最多回复 5 次，超时或超频会发送（回复）失败；
12+
13+
## 使用示例
14+
15+
```js
16+
/** 单聊 */
17+
async function demo() {
18+
const res = await client.C2cAPI.postMessage(openid, message);
19+
}
20+
21+
/** 群聊 */
22+
async function demo() {
23+
const res = await client.GroupAPI.postMessage(group_openid, message);
24+
}
25+
```
26+
27+
## 参数说明
28+
29+
| 字段名 | 必填 | 类型 | 描述 |
30+
| ------- | ---- | -------------------------------------------------------------- | ---------------------------------------------------- |
31+
| openid | 是（单聊） | string | QQ 用户的 openid，可在各类事件中获得。 |
32+
| group_openid | 是（群聊） | string | 群号，可在各类事件中获得。|
33+
| message | 是 | [TMessage](#tmessage) | 消息体 |
34+
35+
36+
### `TMessage`
37+
38+
| 字段 | 类型 | 说明 |
39+
|-------------------|---------------------------|-------------------------------------------------------------------------------------------------------------|
40+
| `content` | `string` | 文本内容 |
41+
| `msg_type` | `0 \| 2 \| 3 \| 4 \| 7` | 消息类型：<br> **`0`** 文本<br> **`2`** markdown<br> **`3`** ark<br> **`4`** embed<br> **`7`** media 富媒体 |
42+
| `markdown` | [`TMarkdown`](#tmarkdown) | Markdown 消息 |
43+
| `keyboard` | [`TKeyboard`](#tkeyboard) | keyboard 消息 |
44+
| `ark` | [`TArk`](#tark) | Ark 消息 |
45+
| `media` | [`TMedia`](#tmedia) | 媒体数据 |
46+
| `message_referance`| `unknown` | 消息引用 <br> @future 暂未支持 |
47+
| `event_id` | `string` | 前置收到的事件 ID，用于发送被动消息 <br> 支持事件：`INTERACTION_CREATE`、`C2C_MSG_RECEIVE` 等 |
48+
| `msg_id` | `string` | 前置收到的用户发送过来的消息 ID，用于发送被动消息（回复） |
49+
| `msg_seq` | `number` | 回复消息的序号，与 `msg_id` 联合使用，避免相同消息 ID 回复重复发送，不填默认是 `1` |
50+
51+
### `TMessageResult`
52+
53+
| 字段 | 类型 | 说明 |
54+
|------------|------------|------------|
55+
| `id` | `string` | 消息唯一 ID |
56+
| `timestamp`| `number` | 发送时间 |
57+
58+
### `TMarkdown`
59+
60+
| 字段 | 类型 | 说明 |
61+
|-------------------|------------------------------|--------------------------|
62+
| `content` | `string` | 原生 markdown 文本内容 |
63+
| `custom_template_id` | `string` | markdown 模版 id |
64+
| `params` | `{ key: unknown; values: unknown }[]` | 模版内变量与填充值的 kv 映射 |
65+
66+
### `TKeyboard`
67+
68+
| 字段 | 类型 | 说明 |
69+
|-------------------|------------------------------|--------------------------|
70+
| `id` | `string` | 按钮 ID，在一个 keyboard 消息内设置唯一 |
71+
| `render_data` | `{ label: string; visited_label: string; style: 0 \| 1; }` | 按钮渲染数据 |
72+
| `action` | `{ type: 0 \| 1 \| 2; permission: { type: 0 \| 1 \| 2 \| 3; specify_user_ids?: string[]; specify_role_ids?: string[]; }; data: string; reply?: boolean; enter?: boolean; anchor?: number; click_limit?: number; at_bot_show_channel_list?: boolean; unsupport_tips: string; }` | 按钮操作数据 |
73+
74+
### `TArk`
75+
76+
| 字段 | 类型 | 说明 |
77+
|-------------------|------------------------------|--------------------------|
78+
| `template_id` | `number` | 模版 id，管理端可获得或内邀申请获得 |
79+
| `kv` | `{ key: string; value: string }[] \| { key: string; obj: { obj_kv: { key: string; value: string }[] }[] }[]` | 模版内变量与填充值的 kv 映射 |
80+
81+
### `TMedia`
82+
83+
| 字段 | 类型 | 说明 |
84+
|-------------------|------------------------------|--------------------------|
85+
| `file_type` | `1 \| 2 \| 3 \| 4` | 媒体类型：<br> **`1`** 图片<br> **`2`** 视频<br> **`3`** 语音<br> **`4`** 文件（暂不开放） |
86+
| `url` | `string` | 需要发送媒体资源的 url |
87+
| `srv_send_msg` | `boolean` | 设置 `true` 会直接发送消息到目标端，且会占用主动消息频次 |
88+
| `file_data` | `unknown` | @future 【暂未支持】 |
89+
| `file_info` | `string` | 来自富媒体消息上传 |
90+
91+
## 返回参数
92+
|属性|类型|说明|
93+
|---|---|---|
94+
|id|string|消息唯一ID|
95+
|timestamp|number|发送时间|
96+
97+
## 返回示例
98+
99+
```json
100+
{
101+
"id": "",
102+
"timestamp": 1688488488
103+
}
104+
```

‎docs/develop/nodesdk/wss/model.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,18 @@ DIRECT_MESSAGE (1 << 12)
2828
- DIRECT_MESSAGE_CREATE // 当收到用户发给机器人的私信消息时
2929
- DIRECT_MESSAGE_DELETE // 删除（撤回）消息事件
3030

31+
GROUP_AND_C2C_EVENT (1 << 25)
32+
- GROUP_ADD_ROBOT // 机器人被添加到群聊
33+
- GROUP_DEL_ROBOT // 机器人被移出群聊
34+
- GROUP_MSG_REJECT // 群管理员主动在机器人资料页操作关闭通知
35+
- GROUP_MSG_RECEIVE // 群管理员主动在机器人资料页操作开启通知
36+
- GROUP_AT_MESSAGE_CREATE // 用户在群聊@机器人发送消息
37+
- C2C_MESSAGE_CREATE // 用户在单聊发送消息给机器人
38+
- FRIEND_ADD // 用户添加机器人'好友'到消息列表
39+
- FRIEND_DEL // 用户删除机器人'好友'
40+
- C2C_MSG_REJECT // 用户在机器人资料卡手动关闭"主动消息"推送
41+
- C2C_MSG_RECEIVE // 用户在机器人资料卡手动开启"主动消息"推送开关
42+
3143
INTERACTION (1 << 26)
3244
- INTERACTION_CREATE // 互动事件创建时
3345

@@ -99,6 +111,9 @@ ws.on('AUDIO_ACTION', data => {
99111
ws.on('PUBLIC_GUILD_MESSAGES', data => {
100112
console.log('[PUBLIC_GUILD_MESSAGES] 事件接收 :', data);
101113
});
114+
ws.on("GROUP_AND_C2C_EVENT", (data) => {
115+
console.log("[GROUP_AND_C2C_EVENT] 事件接收 :", data);
116+
});
102117
```
103118

104119
### 接收到的通知示例

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@
6464
"sync-api": "node scripts/sync-inner-docs/index.js",
6565
"change-log": "node scripts/change-log.js",
6666
"build-tag": "node scripts/add-build-tag.js",
67-
"postinstall":"patch-package"
67+
"postinstall": "patch-package"
6868
},
6969
"dependencies": {
7070
"async-validator": "1.11.5",

0 commit comments

Comments
 (0)