# NodeSDK 接入指南

# 介绍

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

# 安装 qq-guild-bot

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),并拿到相应的BotAppIDBotToken

// 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)
  • 沙箱配置说明:接口域名

注意

  • 事件类型的订阅,是有权限控制的,除了 GUILDSPUBLIC_GUILD_MESSAGESDIRECT_MESSAGEGUILD_MEMBERS 事件是基础的事件,默认有权限订阅之外,其他的特殊事件,都需要经过申请才能够使用,如果在鉴权的时候传递了无权限的 intentswebsocket 会报错,并直接关闭连接

  • intents空数组时,将默认开启全部事件类型的监听。

通过上述示例代码我们可以拿到整个 NodeSDK 最核心的两个对象clientws,整个 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 分三层设计:应用层框架层基础层,具体结构如下图所示:

SDK 底层架构设计
手机QQ扫码
开发者社区
加入官方频道开发者社区