# NodeSDK 接入指南

# 介绍

NodeSDK主要基于基础 API封装，提供给用户一种简单、高效的使用方式。

# 安装

npm i qq-guild-bot

# 或者使用yarn
yarn add qq-guild-bot

# 国内安装可以使用腾讯源
npm i qq-guild-bot --registry=https://mirrors.tencent.com/npm/

1
2
3
4
5
6
7

注意

@tencent-connect/bot-node-sdk已更名为qq-guild-bot。原包已废弃，请使用新包！!

# 使用示例

使用前请先确保已在机器人平台创建机器人 (opens new window)，并拿到相应的BotAppID及BotToken。

// ESModule | TypeScript
// import { createOpenAPI, createWebsocket } from 'qq-guild-bot';

// CommonJs
const { createOpenAPI, createWebsocket } = require('qq-guild-bot');

const testConfig = {
  appID: 'APPID', // 申请机器人时获取到的机器人 BotAppID
  token: 'TOKEN', // 申请机器人时获取到的机器人 BotToken
  intents: ['PUBLIC_GUILD_MESSAGES'], // 事件订阅,用于开启可接收的消息类型
  sandbox: false, // 沙箱支持，可选，默认false. v2.7.0+
};

// 创建 client
const client = createOpenAPI(testConfig);

// 创建 websocket 连接
const ws = createWebsocket(testConfig);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

intents 可选值举例：['GUILDS', 'GUILD_MEMBERS', 'GUILD_MESSAGES','GUILD_MESSAGE_REACTIONS','DIRECT_MESSAGE', 'INTERACTION','MESSAGE_AUDIT','FORUMS_EVENT','AUDIO_ACTION', 'PUBLIC_GUILD_MESSAGES']，详情参考 (opens new window)。
沙箱配置说明：接口域名

注意

事件类型的订阅，是有权限控制的，除了 GUILDS，PUBLIC_GUILD_MESSAGES，DIRECT_MESSAGE，GUILD_MEMBERS 事件是基础的事件，默认有权限订阅之外，其他的特殊事件，都需要经过申请才能够使用，如果在鉴权的时候传递了无权限的 intents，websocket 会报错，并直接关闭连接。
intents传空数组时，将默认开启全部事件类型的监听。

通过上述示例代码我们可以拿到整个 NodeSDK 最核心的两个对象client和ws，整个 SDK 能力将由这两个对象提供。

# 使用 client

client提供了一系列操作频道和发送消息的能力，如：创建频道、创建频道身份组、发送私信等等，具体能力见左侧菜单。

# client 调用示例

以给子频道发送消息为例，使用示例如下：

client.messageApi
  .postMessage(channelID, {
    content: 'messageApi接口触发：hello',
  })
  .then(res => {
    // 数据存储在data中
    console.log(res.data);
  })
  .catch(err => {
    // err信息错误码请参考API文档错误码描述
    console.log(err);
  });

1
2
3
4
5
6
7
8
9
10
11
12

# client 返回示例

client操作的返回结果与REST OPENAPI 接口 (opens new window)保持一致。

{
  "id": "xxxxx",
  "channel_id": "xxxxx",
  "guild_id": "xxxxx",
  "content": "messageApi接口触发：hello",
  "timestamp": "2021-12-03T17:20:00+08:00",
  "tts": false,
  "mention_everyone": false,
  "author": {
    "id": "xxxxx",
    "username": "",
    "avatar": "",
    "bot": true
  },
  "pinned": false,
  "type": 0,
  "flags": 0
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

提示

针对返回失败的情况，可查看错误状态码描述。

# 使用 ws

ws用于频道内消息监听，如要使用client向指定子频道发送消息，必须先建立 ws 连接。

# ws 调用示例

// 消息监听
ws.on('READY', (wsdata) => {
  console.log('[READY] 事件接收 :', wsdata);
});
ws.on('ERROR', (data) => {
  console.log('[ERROR] 事件接收 :', data);
});
ws.on('GUILDS', (data) => {
  console.log('[GUILDS] 事件接收 :', data);
});
ws.on('GUILD_MEMBERS', (data) => {
  console.log('[GUILD_MEMBERS] 事件接收 :', data);
});
ws.on('GUILD_MESSAGES', (data) => {
  console.log('[GUILD_MESSAGES] 事件接收 :', data);
});
ws.on('GUILD_MESSAGE_REACTIONS', (data) => {
  console.log('[GUILD_MESSAGE_REACTIONS] 事件接收 :', data);
});
ws.on('DIRECT_MESSAGE', (data) => {
  console.log('[DIRECT_MESSAGE] 事件接收 :', data);
});
ws.on('INTERACTION', (data) => {
  console.log('[INTERACTION] 事件接收 :', data);
});
ws.on('MESSAGE_AUDIT', (data) => {
  console.log('[MESSAGE_AUDIT] 事件接收 :', data);
});
ws.on('FORUMS_EVENT', (data) => {
  console.log('[FORUMS_EVENT] 事件接收 :', data);
});
ws.on('AUDIO_ACTION', (data) => {
  console.log('[AUDIO_ACTION] 事件接收 :', data);
});
ws.on('PUBLIC_GUILD_MESSAGES', (data) => {
  console.log('[PUBLIC_GUILD_MESSAGES] 事件接收 :', data);
});

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
26
27
28
29
30
31
32
33
34
35
36
37

# ws 返回示例

以下是某个监听的返回示例：

{
  eventType: 'EVENT_TYPE',
  eventId: 'xxx',
  msg: {
    author: {
      avatar: 'xxx',
      bot: false,
      id: 'xxx',
      username: 'xxx,'
    },
    channel_id: 'xxx',
    content: 'xxx',
    guild_id: 'xxx',
    id: 'xxx',
    member: { joined_at: 'xxx', roles: [Array] },
    mentions: [ [Object] ],
    timestamp: 'xxx'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

拿 “创建子频道” 场景举个例子：

// 开启事件监听
ws.on('GUILDS', data => {
  console.log(data);
});

// 创建子频道
client.channelApi.postChannel('GUILD_ID', {
  name: 'test_creation',
  type: 0,
  parent_id: 'CHANNEL_ID',
  owner_id: '0',
  sub_type: 0,
});

1
2
3
4
5
6
7
8
9
10
11
12
13

上述代码打印信息为：

{
  eventType: 'CHANNEL_CREATE',
  eventId: 'xxxxxx',
  msg: {
    guild_id: 'xxxxxx',
    id: 'xxxxxx',
    name: 'test_creation',
    op_user_id: 'xxxxxx',
    owner_id: 'xxxxxx',
    sub_type: 0,
    type: 0
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# SDK 架构说明

整个 SDK 设计与实现基于两条主线：

主动的事件触发
- 频道操作能力：子频道增删改、身份组增删改、成员增删改等。
- 主动消息推送能力。
被动的事件监听
- 通过 websocket 监听事件。

SDK 分三层设计：应用层、框架层、基础层，具体结构如下图所示：

NodeSDK更新日志 →