diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5159b54a..1132620f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,5 +1,6 @@ const { convertSummary } = require('./summary-sidebar'); const nodesdkConfig = require('../develop/nodesdk/config'); +const pythonsdkConfig = require('../develop/pythonsdk/config'); const commonConfig = require('./common'); // openapi 外部文档隐藏的接口,注意不要携带.md后缀 // 废弃，请使用 summary-public 来约束可以展示的内容 @@ -115,6 +116,7 @@ module.exports = ctx => ({ text: 'SDK文档', items: [ nodesdkConfig.nav, + pythonsdkConfig.nav, { text: 'GoSDK', link: 'https://pkg.go.dev/github.com/tencent-connect/botgo', @@ -138,6 +140,7 @@ module.exports = ctx => ({ sidebar: { '/develop/api/': convertSummary('./docs/develop/api/SUMMARY-PUBLIC.md', hiddenApi, 1, true), ...nodesdkConfig.sidebar, + ...pythonsdkConfig.sidebar, '/': [''], }, diff --git a/docs/develop/pythonsdk/README.md b/docs/develop/pythonsdk/README.md new file mode 100644 index 00000000..1052e513 --- /dev/null +++ b/docs/develop/pythonsdk/README.md @@ -0,0 +1,97 @@ +# Python SDK 接入指南 + +## 当前版本 +![PyPI](https://img.shields.io/pypi/v/qq-bot) + +## 安装 + +``` bash +pip install qq-bot +``` + +更新包的话需要添加 ``--upgrade`` ``注：需要python3.7+`` + +## 使用示例-API访问 + +下面的例子，通过api获取当前机器人的相关信息： + +``` py +import qqbot + +token = qqbot.Token("{appid}","{token}") +api = qqbot.UserAPI(token, False) +user = api.me() + +print(user.username) # 打印机器人名字 +``` + +## 使用示例-异步消息 + +通过注册需要监听的事件并设置回调函数后，即可完成对事件的监听。 + +比如下面这个例子：需要监听机器人被@后消息并进行相应的回复。 + +``` py +# 先初始化需要用的 `token` 对象 +t_token = qqbot.Token(test_config["token"]["appid"], test_config["token"]["token"]) +# 通过 `qqbot.HandlerType` 定义需要监听的事件（部分事件可能需要权限申请）可以注册多个 +qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) +# 通过 `qqbot.listen_events` 注册需要监听的事件 +qqbot.listen_events(t_token, False, qqbot_handler) + +# 定义注册事件回调执行函数,如 `_message_handler` +def _message_handler(event, message: Message): + msg_api = qqbot.MessageAPI(t_token, False) + # 打印返回信息 + qqbot.logger.info("event %s" % event + ",receive message %s" % message.content) + # 构造消息发送请求数据对象 + send = qqbot.MessageSendRequest("<@%s>谢谢你，加油" % message.author.id, message.id) + # 通过api发送回复消息 + msg_api.post_message(message.channel_id, send) +``` + +注：当前支持事件及回调事件可参考[事件监听](websocket/listen_events.md#当前支持的事件类型) + +## 日志打印 + +基于自带的 logging 模块封装的日志模块，提供了日志写入以及美化了打印格式，并支持通过设置 `QQBOT_LOG_LEVEL` 环境变量来调整日志打印级别（默认打印级别为 `INFO`）。 + +### 使用方法 + +``` py +# 引用模块 +from core.util import logging + +# 获取 `logger` 实例 +logger = logging.getLogger(__name__) + +# 打印日志 +logger.info("hello world!") +``` + +### 设置日志级别 + +通过 `export` 命令添加 `QQBOT_LOG_LEVEL` 环境变量可以设置日志级别。例如： + +``` bash +export QQBOT_LOG_LEVEL=10 # 10表示DEBUG级别 +``` + +几个可选取值（参考了[logging模块的取值](https://docs.python.org/3/library/logging.html#levels)）： + +| Level | 取值 | +| ----- | ------------- | +| CRITICAL | 50 | +| ERROR | 40 | +| WARNING | 30 | +| INFO | 20 | +| DEBUG | 10 | +| NOTSET | 0 | + +### 禁用日志文件输出 + +默认情况下 qqbot 会在当前执行目录下生成格式为 `qqbot.log.*` 的日志文件。如果想禁用这些日志文件，可以通过设置 `QQBOT_DISABLE_LOG` 环境变量为 1 来关闭。 + +``` bash +export QQBOT_DISABLE_LOG=1 # 1表示禁用日志 +``` diff --git a/docs/develop/pythonsdk/api/audio/post_audio.md b/docs/develop/pythonsdk/api/audio/post_audio.md new file mode 100644 index 00000000..6eae0ca8 --- /dev/null +++ b/docs/develop/pythonsdk/api/audio/post_audio.md @@ -0,0 +1,43 @@ +# 音频控制 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +audioApi = qqbot.AudioAPI(token, False) +result = audioApi.post_audio(channel_id, audio_control) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ------------ | ------------------------------------- | -------------- | +| channel_id | String | 子频道 id | +| audio_control | [AudioControl](#audiocontrol) | audio 控制参数 | + +## 返回说明 + +字段参见 [AudioControl](#audiocontrol) + + +# 语音对象 + +## AudioControl + +| 字段名 | 类型 | 描述 | +| --------- | ------ | --------------------------------------------------------------------- | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | +| status | STATUS | 播放状态，参考 [STATUS](#STATUS) | + +### STATUS + +| 字段名 | 值 | 描述 | +| ------ | --- | ------------ | +| START | 0 | 开始播放操作 | +| PAUSE | 1 | 暂停播放操作 | +| RESUME | 2 | 继续播放操作 | +| STOP | 3 | 停止播放操作 | \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/channel/create_channel.md b/docs/develop/pythonsdk/api/channel/create_channel.md new file mode 100644 index 00000000..e89f1974 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/create_channel.md @@ -0,0 +1,98 @@ +# 创建子频道 + +创建一个子频道。 + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel_res = api.create_channel(channel_id, channel) +``` + +::: warning 注意 + +- 要求操作人具有管理频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。 +- 目前不支持创建的子频道类型 + - 子频道分组 + - 私密子频道 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ---------- | +| guildId | 是 | string | 频道 ID | +| channel | 是 | [Channel](#channel) | 子频道对象 | + +### Channel + +| 字段名 | 类型 | 必填 | 描述 | +| --------- | ------ | ---- | ---------------------------------------------- | +| name | string | 是 | 子频道名 | +| type | number | 是 | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 是 | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 否 | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 否 | 分组 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回说明 + +返回 [ChannelRes](#channelres) 对象。 + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| owner_id | string | 创建者 ID | + +## 返回示例 + +`data`： + +```json +{ + "id": "channel_id", + "guild_id": "guild_id", + "name": "channel_test", + "type": 1, + "position": 1640240055, + "owner_id": "2854198244", + "sub_type": 0 +} +``` diff --git a/docs/develop/pythonsdk/api/channel/delete_channel.md b/docs/develop/pythonsdk/api/channel/delete_channel.md new file mode 100644 index 00000000..6187fece --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/delete_channel.md @@ -0,0 +1,71 @@ +# 删除子频道 + +移除一个子频道。 + + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.delete_channel(channel_id) +``` + +::: warning 注意 + +- 要求操作人具有`管理频道`的权限，如果是机器人，则需要将机器人设置为管理员。 +- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。 +- 子频道的删除是无法撤回的，一旦删除，将无法恢复。 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------ | --------- | +| channel_id | 是 | string | 子频道 ID | + +## 返回说明 + +字段参见 [ChannelRes](#channelres) + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| -------- | ------ | -------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +## 返回示例 + +`data`： + +```json +{ + "id":"channel_id", + "type":0, + "name":"update_channel", + "guild_id":"2020131797974366736" +} +``` diff --git a/docs/develop/pythonsdk/api/channel/get_channel.md b/docs/develop/pythonsdk/api/channel/get_channel.md new file mode 100644 index 00000000..21b226ed --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/get_channel.md @@ -0,0 +1,85 @@ +# 获取子频道信息 + +获取子频道 channel 详情 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.get_channel(channel_id) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ---------- | ------ | --------- | +| channel_id | String | 子频道 ID | + +## 返回说明 + +字段参见 [Channel](#Channel) + + +# 子频道对象(Channel) + +子频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关。请不要理解为真实的 ID + +### Channel +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | String | 子频道id | +| guild_id | String | 频道id | +| name | String | 子频道名 | +| type | int | 子频道类型 [ChannelType](#channeltype) | +| sub_type | int | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | int | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | String | 分组 id | +| owner_id | String | 创建人 id | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知类型的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```json +{ + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":0, + "last_message_id":"21", + "nsfw":false, + "position":2, + "parent_id":"分组 id ", + "rate_limit_per_user":0, + "owner_id":"0", + "sub_type":0 +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/channel/get_channels.md b/docs/develop/pythonsdk/api/channel/get_channels.md new file mode 100644 index 00000000..ac1e5705 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/get_channels.md @@ -0,0 +1,90 @@ +# 获取子频道列表 + +``get_channels`` 获取子频道列表 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.get_channels(guild_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | + +## 返回说明 + +返回 [Channel](#channel) 数组。 + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```json +[ + { + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":4, + "position":2, + "parent_id":"0", + "owner_id":"0", + "sub_type":0 + }, + { + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":4, + "position":3, + "parent_id":"0", + "owner_id":"0", + "sub_type":0 + } +] +``` diff --git a/docs/develop/pythonsdk/api/channel/update_channel.md b/docs/develop/pythonsdk/api/channel/update_channel.md new file mode 100644 index 00000000..bc4c3ccc --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/update_channel.md @@ -0,0 +1,97 @@ +# 修改子频道 + +修改某个子频道的信息。 + + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel_res = api.update_channel(channel_id, channel) +``` + +::: warning 注意 + +- 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 修改成功后，会触发子频道更新事件 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------------------- | ---------- | +| channelId | 是 | string | 子频道 ID | +| channel | 是 | [Channel](#channel) | 子频道对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------ | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +## 返回说明 + +字段参见 [ChannelRes](#channelres)。 + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```json +{ + "id": "2186875", + "guild_id": "2020131797974366736", + "name": "update_channel", + "type": 0, + "position": 22, + "parent_id": "1128421", + "owner_id": null, + "sub_type": 0 +} +``` diff --git a/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md new file mode 100644 index 00000000..4a6c4213 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md @@ -0,0 +1,63 @@ +# 获取子频道权限 + +获取指定子频道的权限。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelPermissionsAPI(token, False) +channel = api.get_channel_permissions(channel_id, user_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------ | --------- | +| channel_id | 是 | string | 子频道 ID | +| user_id | 是 | string | 用户 ID | + +## 返回说明 + +返回 [ChannelPermissions](#channelpermissions) 对象。 + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | --------------------------- | --------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | [permissions](#permissions) | 用户拥有的子频道权限，是个 string | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | + +## 返回示例 + +`data`： + +```json +{ + "channel_id": "1128412", + "user_id": "9962144428931019739", + "permissions": "6" +} +``` diff --git a/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md b/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md new file mode 100644 index 00000000..7e07917e --- /dev/null +++ b/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md @@ -0,0 +1,67 @@ +# 修改子频道权限 + +修改子频道权限。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelPermissionsAPI(token, False) +channel = api.update_channel_permissions(channel_id, user_id, channel_permissions) +``` + +::: warning 注意 + +- 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 参数包括 add 和 remove 两个字段，分别表示授予的权限以及删除的权限。要授予用户权限即把 add 对应位置 1，删除用户权限即把 remove 对应位置 1。当两个字段同一位都为 1，表现为删除权限。 +- 本接口不支持修改可管理子频道权限。 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------------------ | ---- | ----------------------------------------- | --------- | +| channel_id | 是 | string | 子频道 ID | +| user_id | 是 | string | 用户 ID | +| channel_permissions | 是 | [ChannelPermissions](#channelpermissions) | 权限参数 | + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | --------------------------- | --------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | [permissions](#permissions) | 用户拥有的子频道权限，是个 string | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | + +## 返回说明 + +返回是否更新成功 + +## 返回示例 + +`data`： + +```Python +True +``` diff --git a/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md b/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md new file mode 100644 index 00000000..ced9e625 --- /dev/null +++ b/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md @@ -0,0 +1,55 @@ +# 创建私信会话 + +## 功能描述 + +- 机器人和同在一个频道内的成员创建私信会话。 +- 创建成功后，返回创建成功的频道 id ，子频道 id 和创建时间。 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.MessageAPI(token, False) +request = CreateDirectMessageRequest("guild_id", "user_id") +direct_message_guild = api.create_direct_message_guild(request) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | --------- | +| request | [CreateDirectMessageRequest](#CreateDirectMessageRequest) | 私信频道创建请求 | + +## CreateDirectMessageRequest + +| 字段名 | 类型 | 描述 | +| --------------- | ------ | --------- | +| source_guild_id | string | 源频道 ID | +| user_id | string | 接收者 ID | + +## 返回说明 + +成功创建后，返回[DirectMessageGuild](#DirectMessageGuild)对象返回创建成功的频道 ID，子频道 ID 和创建时间。 + +## DirectMessageGuild + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | --------- | +| guild_id | string | 频道 ID | +| channel_id | string | 子频道 ID | +| create_time | string | 创建时间 | + +## 返回示例 + +`data`： + +```json +{ + "guild_id": "xxxxxx", + "channel_id": "xxxxxx", + "create_time": "1638323931" +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md b/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md new file mode 100644 index 00000000..29eb4e10 --- /dev/null +++ b/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md @@ -0,0 +1,32 @@ +# 发送私信消息 + +## 功能描述 + +- 发送私信消息 +- 私信的 guild_id 在[创建私信会话](create_direct_message.md)时以及[私信消息事件](../../websocket/listen_events.md)中获取 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.MessageAPI(token, False) +message = api.post_direct_message(guild_id, send_msg) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ------ | ------------------------------------------------------ | ------ | +| guild_id | string | 创建的私信会话频道[guild_id](create_direct_message.md#返回说明) | +| send_msg | [MessageSendRequest](../message/post_message#MessageSendRequest) | 消息体 | + +## 返回说明 + +返回[Message](../message/post_message.md#message) 对象 + +## 返回示例 + +同[发送消息返回示例](../message/post_message.md#返回示例) diff --git a/docs/develop/pythonsdk/api/guild/get_guild.md b/docs/develop/pythonsdk/api/guild/get_guild.md new file mode 100644 index 00000000..bafb37cb --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/get_guild.md @@ -0,0 +1,52 @@ +# 获取频道详情 + +获取频道详情信息。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildAPI(token, False) +guild = api.get_guild(guild_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | + +## 返回说明 + +返回 [Guild](#guild) 对象。 + +### Guild + +| 字段名 | 类型 | 描述 | +| ------------ | ------- | ------------------ | +| id | string | 频道 ID | +| name | string | 频道名称 | +| owner_id | string | 创建人用户 ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | + +## 返回示例 + +`data`： + +```json +{ + "id":"guildId", + "name":"频道名称", + "owner_id":"owner_id", + "owner":false, + "member_count":8, + "max_members":300, + "description":"" +} +``` diff --git a/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md new file mode 100644 index 00000000..00b01790 --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md @@ -0,0 +1,51 @@ +# 创建频道身份组 + +创建一个频道身份组。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.create_guild_role(guild_id,role_info) +``` + +::: warning 注意 +需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。 +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| -------- | ---- | --------------------- | -------------- | +| guild_id | 是 | string | 频道 ID | +| role_info | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | + +### RoleInfo + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | -------------------------------------------------------------- | +| name | 是 | string | 名称 | +| color | 否 | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | 否 | number | 在成员列表中单独展示: 0-否, 1-是 | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------- | -------------- | +| role_id | string | 频道身份组 ID | +| role | [GuildRole](#guildrole) | 频道身份组对象 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | diff --git a/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md new file mode 100644 index 00000000..d461c9cd --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md @@ -0,0 +1,48 @@ +# 创建频道身份组成员 + +创建频道身份组成员。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.create_guild_role_member(guild_id, role_id, user_id, channel) +``` + +::: warning 注意 + +- 需要使用的 `token` 对应的用户具备增加身份组成员权限，如果是机器人，要求被添加为管理员。 +- 如果要增加的身份组 `ID` 是子频道管理员，需要增加 `Channel` 对象来指定具体是哪个子频道。 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ------------------------------------ | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| user_id | 是 | string | 用户 ID | +| channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| ------ | ------ | --------- | +| id | string | 子频道 ID | + +## 返回说明 + +添加是否成功 + +## 返回示例 + +`data`: + +```python +True +``` diff --git a/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md new file mode 100644 index 00000000..2082e96f --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md @@ -0,0 +1,31 @@ +# 删除频道身份组 + +删除频道身份组。 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.delete_guild_role(guild_id, role_id) +``` + +### 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| ------- | ---- | ------ | --------- | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | + +### 返回说明 + +是否删除成功 + +### 返回示例 + +`data`： + +```python +True +``` diff --git a/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md new file mode 100644 index 00000000..f37689ab --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md @@ -0,0 +1,47 @@ +# 删除频道身份组成员 + +删除频道身份组成员。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.delete_guild_role_member(guild_id, role_id, user_id, channel) +``` + +::: warning 注意 + +- 需要使用的 token 对应的用户具备删除身份组成员权限。如果是机器人，要求被添加为管理员。 +- 如果要删除的身份组 ID 是`5-子频道管理员`，需要增加 channel 对象来指定具体是哪个子频道 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ------------------------------------ | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| user_id | 是 | string | 用户 ID | +| channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| ------ | ------ | --------- | +| id | string | 子频道 ID | + +## 返回说明 + +返回删除是否成功 + +## 返回示例 + +`data`: + +```python +True +``` diff --git a/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md new file mode 100644 index 00000000..ce760189 --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md @@ -0,0 +1,67 @@ +# 获取频道身份组列表 + +获取频道身份组列表。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +guild_roles = api.get_guild_roles(guild_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| -------- | ----------------------- | ------------------ | +| guild_id | string | 频道 ID | +| roles | [GuildRole[]](#guildrole) | 频道身份组对象数组 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +## 返回示例 + +`data`： + +```json +{ + "guild_id":"guild_id", + "roles":[ + { + "id":"4", + "name":"名称", + "color":4294927682, + "hoist":1, + "number":1, + "member_limit":1 + }, + { + "id":"2", + "name":"名称", + "color":4280276644, + "hoist":1, + "number":4, + "member_limit":50 + } + ], + "role_num_limit":"30" +} +``` diff --git a/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md new file mode 100644 index 00000000..dcbf66a5 --- /dev/null +++ b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md @@ -0,0 +1,71 @@ +# 修改频道身份组 + +修改频道身份组信息。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.update_guild_role(guild_id, role_id, role_info) +``` + +:::warning 注意 +需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员 +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| -------- | ---- | --------------------- | -------------- | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| role_info | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | + +### RoleInfo + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | -------------------------------------------------------------- | +| name | 是 | string | 名称 | +| color | 否 | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | 否 | number | 在成员列表中单独展示: 0-否, 1-是 | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| -------- | ----------------------- | -------------- | +| guild_id | string | 频道 ID | +| role_id | string | 身份组 ID | +| role | [GuildRole](#guildrole) | 频道身份组对象 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +## 返回示例 + +`data`： + +```python +{ + "guild_id": "guild_id", + "role_id": "role_id", + "role": { + "id": "role_id", + "name": "Test Update Role", + "color": 4278245297, + "hoist": 0, + "number": 0, + "member_limit": 2000} +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/member/delete_guild_member.md b/docs/develop/pythonsdk/api/member/delete_guild_member.md new file mode 100644 index 00000000..1486fde5 --- /dev/null +++ b/docs/develop/pythonsdk/api/member/delete_guild_member.md @@ -0,0 +1,36 @@ +# 删除频道成员 + +移除频道的某个成员。 + + + +## 使用示例 + +```python +# TODO:施工中 +``` + +::: warning 注意 + +- 需要使用的 token 对应的用户具备踢人权限。如果是机器人，要求被添加为管理员。 +- 操作成功后，会触发频道成员删除事件 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | +| user_id | 是 | string | 用户 ID | + +## 返回说明 + +无 + +## 返回示例 + +`data`: + +```js +''; +``` diff --git a/docs/develop/pythonsdk/api/member/get_guild_member.md b/docs/develop/pythonsdk/api/member/get_guild_member.md new file mode 100644 index 00000000..afa164bc --- /dev/null +++ b/docs/develop/pythonsdk/api/member/get_guild_member.md @@ -0,0 +1,67 @@ +# 获取频道成员详情 + +获取频道下某个成员的信息。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) +api = qqbot.GuildMemberAPI(token, False) +members = api.get_guild_member(guild_id, user_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | +| user_id | 是 | string | 用户 ID | + +## 返回说明 + +返回 [Member](model.md) 对象。 + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | ------------- | -------------------------------------------------------------------------------------------- | +| user | [User](#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](../guild/role_model.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | + +## 返回示例 + +`data`： + +```json +{ + "user": { + "id": "用户 ID", + "username": "用户名", + "avatar": "用户头像地址", + "bot": false, + "public_flags": 0, + "system": false + }, + "nick": "", + "roles": [ + "4" + ], + "joined_at": "2021-09-27T17:19:51+08:00", + "deaf": false, + "mute": false, + "pending": false +} +``` diff --git a/docs/develop/pythonsdk/api/member/get_guild_members.md b/docs/develop/pythonsdk/api/member/get_guild_members.md new file mode 100644 index 00000000..8225e318 --- /dev/null +++ b/docs/develop/pythonsdk/api/member/get_guild_members.md @@ -0,0 +1,78 @@ +# 获取频道成员列表 + +获取频道下的成员列表。 + + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) +api = qqbot.GuildMemberAPI(token, False) +members = api.get_guild_members(guild_id, query_params) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ----------- | ---- | --------------------------- | -------- | +| guild_id | 是 | string | 频道 ID | +| query_params | 否 | [QueryParams](#queryparams) | 查询参数 | + +### QueryParams + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | ---------------------------------------------------------- | +| after | 否 | string | 上一次回包中最大的用户 ID， 如果是第一次请求填 0，默认为 0 | +| limit | 否 | number | 分页大小，1-1000，默认是 1 | + +## 返回说明 + +返回 [Member](#member) 对象。 + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | ------------- | -------------------------------------------------------------------------------------------- | +| user | [User](#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](../guild/role_model.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | + +## 返回示例 + +`data`： + +```json +[ + { + "user": { + "id": "USERID", + "username": "机器人管家-ostwindli", + "avatar": "http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059", + "bot": false, + "public_flags": 0, + "system": false + }, + "nick": "阿青", + "roles": [ + "4" + ], + "joined_at": "2021-11-23T15:16:48+08:00", + "deaf": false, + "mute": false, + "pending": false + } +] +``` diff --git a/docs/develop/pythonsdk/api/message/get_message.md b/docs/develop/pythonsdk/api/message/get_message.md new file mode 100644 index 00000000..37880c46 --- /dev/null +++ b/docs/develop/pythonsdk/api/message/get_message.md @@ -0,0 +1,90 @@ +# 获取指定消息 + +获取指定消息。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.get_message(channel_id,message_id) +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ------ | --------- | +| channel_id | 是 | string | 子频道 ID | +| message_id | 是 | string | 消息 ID | + +## 返回说明 + +| 参数 | 类型 | 说明 | +| ------- | ------------------- | ----------------- | +| message | [Message](#message) | 返回 message 对象 | + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +`data`: + +```json +{ + "message": { + "id": "abcdef01", + "channel_id": "100001", + "guild_id": "100000000001", + "content": "hello", + "timestamp": "2021-05-25T15:20:34+08:00", + "author": { + "id": "1000000001", + "username": "az", + "bot": false + }, + "member": { + "roles": ["1"], + "joined_at": "2021-04-12T16:34:42+08:00" + } + } +} +``` diff --git a/docs/develop/pythonsdk/api/message/get_messages.md b/docs/develop/pythonsdk/api/message/get_messages.md new file mode 100644 index 00000000..e35154b5 --- /dev/null +++ b/docs/develop/pythonsdk/api/message/get_messages.md @@ -0,0 +1,128 @@ +# 拉取消息列表 + +获取消息列表。 + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.get_messages(channel_id,pager) +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ------------------------------- | --------- | +| channel_id | 是 | string | 子频道 ID | +| pager | 否 | [MessagesPager](#messagespager) | 分页信息 | + +### MessagesPager + +| 参数 | 必填 | 类型 | 说明 | +| ----- | ---- | ----------------------- | ----------------------------- | +| type | 是 | [TypesEnum](#typesenum) | 拉取类型 | +| id | 是 | string | 消息 ID | +| limit | 是 | string | 每次拉取多少条消息，最大 `20` | + +### TypesEnum + +| 字段名 | 类型 | 描述 | +| -------- | ------ | ------------------ | +| `around` | string | 读此 id 前后的消息 | +| `before` | string | 读此 id 之前的消息 | +| `after` | string | 读此 id 之后的消息 | +| `latest` | string | 最新limit的消息 | + +如果 `around/before/after` 均为`空`，则拉取最新的 `limit` 条消息。 + +## 返回说明 + +返回 [Message](#message) 对象数组。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +`data`： + +```json +[ + { + "id": "xxx", + "channel_id": "100001", + "guild_id": "100000000001", + "content": "hello", + "timestamp": "2021-05-25T15:20:34+08:00", + "author": { + "id": "1000000001", + "username": "az", + "bot": false + }, + "member": { + "roles": [ + "1" + ], + "joined_at": "2021-04-12T16:34:42+08:00" + } + }, + { + "id": "yyy", + "channel_id": "100001", + "guild_id": "1000000000001", + "content": "world", + "timestamp": "2021-05-25T15:20:32+08:00", + "author": { + "id": "10000001", + "username": "az", + "bot": false + }, + "member": { + "roles": [ + "1" + ], + "joined_at": "2021-04-12T16:34:42+08:00" + } + } +] +``` diff --git a/docs/develop/pythonsdk/api/message/message_format.md b/docs/develop/pythonsdk/api/message/message_format.md new file mode 100644 index 00000000..a59e0606 --- /dev/null +++ b/docs/develop/pythonsdk/api/message/message_format.md @@ -0,0 +1,132 @@ +# 消息内嵌格式 + +::: warning 注意 + +- 消息不支持 markdown 格式，会自动移除 markdown 格式 +- 内嵌格式仅在 content 中会生效，在 Ark 和 Embed 中不生效 + +::: + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | + +## MessageSendRequest + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，参考[支持的格式](#支持的格式) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间 | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +### 支持的格式 + +| 类型 | 结构 | 描述 | 示例 | +| :------ | :------------ | :------------------------------------------------------------------ | :--------------- | +| @用户 | <@user_id> | 解析为 @用户 标签 | <@1234000000001> | +| #子频道 | <#channel_id> | 解析为 #子频道 标签，点击可以跳转至子频道，仅支持当前频道内的子频道 | <#12345> | + +## 返回说明 + +返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +以发送文本内容`<@!1234>hello world`为例，下面是返回示例： + +`data`: + +```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/pythonsdk/api/message/message_template.md b/docs/develop/pythonsdk/api/message/message_template.md new file mode 100644 index 00000000..537187b3 --- /dev/null +++ b/docs/develop/pythonsdk/api/message/message_template.md @@ -0,0 +1,376 @@ +# 消息模板 + +为了丰富消息内容，SDK 提供了几种消息模板。 + +::: warning 注意 + +- 发送消息时所有字段均使用`字符串类型`。 +- 如果发送的消息中包含链接（网页、图片、视频链接等），**需要提前在[机器人管理端](https://bot.q.qq.com/#/developer/developer-setting)报备**，操作流程：操作路径为：”开发设置“ -> ”消息 URL 配置“。 + +::: + +## 可用模板 + +- [链接+文本列表模板](#链接、文本列表模板) +- [文本+缩略图模板](#文本、缩略图模板) +- [大图模板](#大图模板34) + +## 链接、文本列表模板 + +### 样式(id=23) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.channel.robot", + "view": "albumAddPic", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "list": "#LIST#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------- | :----- | :--------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示消息 | +| #LIST# | array | #LIST#数组 | + +### LIST 结构 + +| 字段名 | 类型 | 描述 | +| :----- | :----- | :------------------------------------------------------------- | +| desc | string | 文本内容 | +| link | string | 链接，需要提前报备，如果不填就显示为文本，如果填了就显示为链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 23, + "kv": [ + { + "key": "#DESC#", + "value": "descaaaaaa" + }, + { + "key": "#PROMPT#", + "value": "promptaaaa" + }, + { + "key": "#LIST#", + "obj": [ + { + "obj_kv": [ + { + "key": "desc", + "value": "需求标题：UI问题解决" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "当前状态\"体验中\"点击下列动作直接扭转状态到：" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "已评审" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "已排期" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "开发中" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "增量测试中" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "请关注" + } + ] + } + ] + } + ] + } +} +``` + +## 文本、缩略图模板 + +### 样式(id=24) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.channelrobot.smallpic", + "view": "albumAddPic", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "title": "#TITLE#", + "desc": "#METADESC#", + "img": "#IMG#", + "link": "#LINK#", + "subTitle": "#SUBTITLE#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :--------- | :----- | :------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示文本 | +| #TITLE# | string | 标题 | +| #METADESC# | string | 详情描述 | +| #IMG# | string | 图片链接 | +| #LINK# | string | 跳转链接 | +| #SUBTITLE# | string | 来源 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 24, + "kv": [ + { + "key": "#DESC#", + "value": "描述描述描放假大方了大家反垄断撒娇两款发动机临时卡封疆大吏撒酒疯；里导数据阿弗莱克的撒娇；廊坊述" + }, + { + "key": "#PROMPT#", + "value": "通知信息xxxxx" + }, + { + "key": "#TITLE#", + "value": "标题fjd;lsajfldjsalkfjdkw封疆大吏撒娇锋利的撒娇；付了定金撒标题标题标题标题fjkdlajfldjal;fd放大了发动机上来空" + }, + { + "key": "#METADESC#", + "value": "Meta描述描述描述风好大换热器继往开来积分考虑到；安静了；了；防静电；来撒会今日而我却哦iopqwfjldsa" + }, + { + "key": "#IMG#", + "value": "https://pub.idqqimg.com/pc/misc/files/20190820/2f4e70ae3355ece23d161cf5334d4fc1jzjfmtep.png" + }, + { + "key": "#LINK#", + "value": "https://qq.com" + }, + { + "key": "#SUBTITLE#", + "value": "子标题" + } + ] + } +} +``` + +## 大图模板 34 + +### 样式(id=34) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.miniapp_01", + "view": "view_8C8E89B49BE609866298ADDFF2DBABA4", + "ver": "1.0.1.12", + "desc": "#DESC#", + "prompt": "#PROMPT#", + "meta": { + "detail_1": { + "title": "#METATITLE#", + "desc": "#METADESC#", + "icon": "#METAICON#", + "preview": "#METAPREVIEW#", + "url": "#METAURL#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------------ | :----- | :------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示消息 | +| #METATITLE# | string | 标题 | +| #METADESC# | string | 描述 | +| #METAICON# | string | 小图标 | +| #METAPREVIEW# | string | 大图 | +| #METAURL# | string | 跳转链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 34, + "kv": [ + { + "key": "#DESC#", + "value": "descaaaaaa" + }, + { + "key": "#PROMPT#", + "value": "promptaaaa" + }, + { + "key": "#METATITLE#", + "value": "metatitle" + }, + { + "key": "#METADESC#", + "value": "metadesc" + }, + { + "key": "#METAICON#", + "value": "https://tangram-1251316161.file.myqcloud.com/files/20211014/bfd7d02235e52d60b05a630ac9ef8bcc.png" + }, + { + "key": "#METAPREVIEW#", + "value": "https://tangram-1251316161.file.myqcloud.com/files/20211014/bfd7d02235e52d60b05a630ac9ef8bcc.png" + }, + { + "key": "#METAURL#", + "value": "https://qq.com" + } + ] + } +} +``` + +## 大图模板 37 + +### 样式(id=37) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.imagetextbot", + "view": "index", + "ver": "1.0.0.11", + "prompt": "#PROMPT#", + "meta": { + "robot": { + "title": "#METATITLE#", + "subtitle": "#METASUBTITLE#", + "cover": "#METACOVER#", + "jump_url": "#METAURL#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------------- | :----- | :-------------------- | +| #PROMPT# | string | 提示消息 | +| #METATITLE# | string | 标题 | +| #METASUBTITLE# | string | 子标题 | +| #METACOVER# | string | 大图，尺寸为 975\*540 | +| #METAURL# | string | 跳转链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 37, + "kv": [ + { + "key": "#PROMPT#", + "value": "通知提醒" + }, + { + "key": "#METATITLE#", + "value": "标题" + }, + { + "key": "#METASUBTITLE#", + "value": "子标题" + }, + { + "key": "#METACOVER#", + "value": "https://vfiles.gtimg.cn/vupload/20211029/bf0ed01635493790634.jpg" + }, + { + "key": "#METAURL#", + "value": "https://qq.com" + } + ] + } +} +``` diff --git a/docs/develop/pythonsdk/api/message/post_ark_message.md b/docs/develop/pythonsdk/api/message/post_ark_message.md new file mode 100644 index 00000000..aad780b3 --- /dev/null +++ b/docs/develop/pythonsdk/api/message/post_ark_message.md @@ -0,0 +1,226 @@ +# 发送模板消息 + +::: warning 注意 + +- 要求操作人在该子频道具有`发送消息`和 `模板消息` 的权限。 +- 调用前需要先申请消息模板，这一步会得到一个模板 id，在请求时填在 ark.template_id 上 +- 发送成功之后，会触发一个创建消息的事件。 +- 可用模板参考[可用模板](message_template.md) +- 如果发送的消息中包含链接（网页、图片、视频链接等），**需要提前在[机器人管理端](https://bot.q.qq.com/#/developer/developer-setting)报备**，操作流程：操作路径为：”开发设置“ -> ”消息 URL 配置“ + +::: + +## 使用示例 + +需要关注`ark`字段的使用。 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | + +## MessageSendRequest + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间 | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +### 参数示例 + +假设模板如下，其中`#META_LIST#`类型为数组、`#META_URL#`类型为 `URL`、其他为文本。 + +```json +{ + "app": "com.tencent.miniapp", + "view": "detail", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "title": "#TITLE#", + "desc": "#META_DESC#", + "url": "#META_URL#", + "list": "#META_LIST#" + } + } +} +``` + +请求体中的 ark 内容为 + +```json +{ + "ark": { + "template_id": 1, + "kv": [ + { + "key": "#DESC#", + "value": "机器人订阅消息" + }, + { + "key": "#PROMPT#", + "value": "XX机器人" + }, + { + "key": "#TITLE#", + "value": "XX机器人消息" + }, + { + "key": "#META_URL#", + "value": "http://domain.com/" + }, + { + "key": "#META_LIST#", + "obj": [ + { + "obj_kv": [ + { + "key": "name", + "value": "aaa" + }, + { + "key": "age", + "value": "3" + } + ] + }, + { + "obj_kv": [ + { + "key": "name", + "value": "bbb" + }, + { + "key": "age", + "value": "4" + } + ] + } + ] + } + ] + } +} +``` + +则实际下发的 json 为 + +```json +{ + "app": "com.tencent.miniapp", + "view": "detail", + "ver": "0.0.0.1", + "desc": "机器人订阅消息", + "prompt": "[QQ小程序]XX机器人", + "meta": { + "detail": { + "title": "XX机器人消息", + "url": "http://domain.com/", + "list": [ + { "name": "aaa", "age": "3" }, + { "name": "bbb", "age": "4" } + ] + } + } +} +``` + +## 返回说明 + +返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 id | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| edited_timestamp | string | 消息编辑时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| mention_everyone | boolean | 是否是@全员消息 | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +```json +{ + "id": "101234567890abcdef", + "channel_id": "10001", + "guild_id": "6400000001", + "content": "<@!1234>hello world", + "timestamp": "2021-05-13T14:45:45+08:00", + "tts": false, + "mention_everyone": false, + "author": { + "id": "12345", + "username": "abc", + "avatar": "", + "bot": true + }, + "pinned": false, + "type": 0, + "flags": 0 +} +``` diff --git a/docs/develop/pythonsdk/api/message/post_message.md b/docs/develop/pythonsdk/api/message/post_message.md new file mode 100644 index 00000000..283f84aa --- /dev/null +++ b/docs/develop/pythonsdk/api/message/post_message.md @@ -0,0 +1,138 @@ +# 发送消息 + +向指定子频道推送消息。 + +::: warning 注意 + +- 要求操作人在该子频道具有`发送消息`的权限。 +- 发送成功之后，会触发一个创建消息的事件。 +- 被动回复消息有效期为 `5` 分钟。 +- 主动推送消息每日每个子频道限 `2` 条。 +- **发送消息接口要求机器人接口需要链接到 `websocket gateway` 上保持在线状态** + +::: + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | + +## MessageSendRequest + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ---------------------------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为[被动回复消息](#被动回复消息)，否则视为主动推送消息** | + +`content`、`embed`、`ark`、`image`**至少需要有一个字段**，否则无法下发消息。 + +### 被动回复消息 + +::: warning 注意 + +被动消息需是用户`@机器人`的消息，否则将会报错。 + +::: + +## MessageEmbed + +详见[消息内嵌格式](message_format.md)。 + +## MessageArk + +详见[发送模板消息](post_ark_message.md)。 + +## 返回说明 + +主动消息都需要审核，返回结果如下： + +```json +{ + "code": 304023, + "message": "push message is waiting for audit now" +} +``` + +若为私域机器人可正常返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +以发送文本内容`hello world`为例，下面是返回示例： + +`data`: + +```json +{ + "id": "101234567890abcdef", + "channel_id": "10001", + "guild_id": "6400000001", + "content": "hello world", + "timestamp": "2021-05-13T14:45:45+08:00", + "tts": false, + "mention_everyone": false, + "author": { + "id": "12345", + "username": "abc", + "avatar": "", + "bot": true + }, + "embeds": [{}], + "pinned": false, + "type": 0, + "flags": 0 +} +``` diff --git a/docs/develop/pythonsdk/api/user/me.md b/docs/develop/pythonsdk/api/user/me.md new file mode 100644 index 00000000..abd4d030 --- /dev/null +++ b/docs/develop/pythonsdk/api/user/me.md @@ -0,0 +1,40 @@ +# 获取当前用户信息 + +## 使用示例 + +``` python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.UserAPI(token, False) +user = api.me() +``` + +## 返回说明 + +使用当前用户信息填充的 [User](#user) 对象 + +### User + +| 字段名 | 类型 | 描述 | +| ------------------ | ------- | -------------------------------------------------------------------------------------------------- | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| union_openid | string | 特殊关联应用的 openid，需要特殊申请并配置后才会返回。如需申请，请联系平台运营人员。 | +| union_user_account | string | 机器人关联的互联应用的用户信息，与 union_openid 关联的应用是同一个。如需申请，请联系平台运营人员。 | + +## 返回示例 + +`data`： + +```json +{ + "id": "xxxxxx", + "username": "zsh-测试中", + "avatar": "xxxxxx", + "union_openid": "xxxxxx", + "union_user_account": "" +} +``` diff --git a/docs/develop/pythonsdk/api/user/me_guilds.md b/docs/develop/pythonsdk/api/user/me_guilds.md new file mode 100644 index 00000000..5211c976 --- /dev/null +++ b/docs/develop/pythonsdk/api/user/me_guilds.md @@ -0,0 +1,26 @@ +# 获取当前用户频道列表 + +### 使用示例 +``` python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.UserAPI(token, False) +user = api.me_guilds() +``` + +### 返回说明 +当前用户所加入的所有 [Guild](#Guild) 对象列表 + +### Guild + +| 字段名 | 类型 | 描述 | +| ------------ | ------- | ------------------ | +| id | string | 频道 ID | +| name | string | 频道名称 | +| owner_id | string | 创建人用户 ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | diff --git a/docs/develop/pythonsdk/config.js b/docs/develop/pythonsdk/config.js new file mode 100644 index 00000000..2514cf41 --- /dev/null +++ b/docs/develop/pythonsdk/config.js @@ -0,0 +1,120 @@ +module.exports = { + nav: { + text: 'PythonSDK', + link: '/develop/pythonsdk/', + }, + sidebar: { + '/develop/pythonsdk/': [ + '', + { + title: '术语', + collapsable: false, + sidebarDepth: 0, + children: [ + {title: '用户对象(User)', path: 'model/user'}, + {title: '频道对象(Guild)', path: 'model/guild'}, + {title: '子频道对象(Channel)', path: 'model/channel'}, + {title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission'}, + {title: '成员对象(Member)', path: 'model/member'}, + {title: '频道身份组对象(Role)', path: 'model/role'}, + {title: '消息对象(Message)', path: 'model/message'}, + {title: '语音对象(Audio)', path: 'model/audio'}, + ], + }, + { + title: 'Client API', + collapsable: false, + children: [ + { + title: '用户 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/user/me', + 'api/user/me_guilds' + ], + }, + { + title: '频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/get_guild' + ], + }, + { + title: '子频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel/get_channel', + 'api/channel/get_channels', + 'api/channel/create_channel', + 'api/channel/update_channel', + 'api/channel/delete_channel', + ], + }, + { + title: '子频道权限 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel_permissions/get_channel_permissions', + 'api/channel_permissions/update_channel_permissions', + ], + }, + { + title: '成员 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/member/get_guild_member', + 'api/member/get_guild_members', + 'api/member/delete_guild_member' + ], + }, + { + title: '频道身份组 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/guild_role/get_guild_roles', + 'api/guild/guild_role/create_guild_role', + 'api/guild/guild_role/update_guild_role', + 'api/guild/guild_role/delete_guild_role', + 'api/guild/guild_role/create_guild_role_member', + 'api/guild/guild_role/delete_guild_role_member' + ], + }, + { + title: '消息 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/message/get_message', + 'api/message/get_messages', + 'api/message/post_message', + 'api/message/post_ark_message', + 'api/message/message_template', + 'api/message/message_format', + ], + }, + { + title: '音频 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/audio/post_audio' + ], + }, + ], + }, + { + title: 'WebSocket API', + collapsable: false, + sidebarDepth: 0, + children: [{title: '事件监听', path: 'websocket/listen_events.md'}], + }, + ], + }, +}; diff --git a/docs/develop/pythonsdk/model/audio.md b/docs/develop/pythonsdk/model/audio.md new file mode 100644 index 00000000..b28185de --- /dev/null +++ b/docs/develop/pythonsdk/model/audio.md @@ -0,0 +1,27 @@ +# 语音对象(AudioControl) + +## AudioControl + +| 字段名 | 类型 | 描述 | +| --------- | ----------------- | --------------------------------------------------------------------- | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | +| status | [STATUS](#status) | 播放状态，参考 STATUS | + +## STATUS + +| 字段名 | 值 | 描述 | +| ------ | --- | ------------ | +| START | 0 | 开始播放操作 | +| PAUSE | 1 | 暂停播放操作 | +| RESUME | 2 | 继续播放操作 | +| STOP | 3 | 停止播放操作 | + +## AudioAction + +| 字段名 | 类型 | 描述 | +| ---------- | ------ | --------------------------------------------------------------------- | +| guild_id | string | 频道 ID | +| channel_id | string | 子频道 ID | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | diff --git a/docs/develop/pythonsdk/model/channel.md b/docs/develop/pythonsdk/model/channel.md new file mode 100644 index 00000000..c8af3cff --- /dev/null +++ b/docs/develop/pythonsdk/model/channel.md @@ -0,0 +1,42 @@ +# 子频道对象(Channel) + +子频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +注：目前只有`文字子频道`具有 `ChannelSubType` 二级分类，同时二级分类也可能会不断增加，开发者也需要注意对未知 ID 的处理。 diff --git a/docs/develop/pythonsdk/model/channel_permission.md b/docs/develop/pythonsdk/model/channel_permission.md new file mode 100644 index 00000000..dd0d9a4a --- /dev/null +++ b/docs/develop/pythonsdk/model/channel_permission.md @@ -0,0 +1,27 @@ +# 子频道权限对象(ChannelPermissions) + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | ----------------------------------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | string | 用户拥有的子频道权限，具体值参考[permissions](#permissions) | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | diff --git a/docs/develop/pythonsdk/model/dms.md b/docs/develop/pythonsdk/model/dms.md new file mode 100644 index 00000000..f0206ed6 --- /dev/null +++ b/docs/develop/pythonsdk/model/dms.md @@ -0,0 +1,9 @@ +# 私信会话对象（DMS） + +## DMS + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | ----------------------- | +| guild_id | string | 私信会话关联的频道 ID | +| channel_id | string | 私信会话关联的子频道 ID | +| create_time | string | 创建私信会话时间戳 | diff --git a/docs/develop/pythonsdk/model/guild.md b/docs/develop/pythonsdk/model/guild.md new file mode 100644 index 00000000..4a97334a --- /dev/null +++ b/docs/develop/pythonsdk/model/guild.md @@ -0,0 +1,17 @@ +# 频道对象(Guild) + +频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +### Guild + +| 字段名 | 类型 | 描述 | +| --- | --- | --- | +| id | string | 频道ID | +| name | string | 频道名称 | +| icon | string | 频道头像地址 | +| owner_id | string | 创建人用户ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | +| joined_at | string | 加入时间 | diff --git a/docs/develop/pythonsdk/model/member.md b/docs/develop/pythonsdk/model/member.md new file mode 100644 index 00000000..e82dada4 --- /dev/null +++ b/docs/develop/pythonsdk/model/member.md @@ -0,0 +1,20 @@ +# 成员对象(Member) + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | -------------------------- | -------------------------------------------------------------------------------------- | +| user | [User](/user#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](role.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### MemberWithGuildID + +| 字段名 | 类型 | 描述 | +| --------- | ----------------------------- | ------------------------------------------------------------------------------------ | +| guild_id | string | 频道 ID | +| user | [User](user) | 用户基础信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份 | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | diff --git a/docs/develop/pythonsdk/model/message.md b/docs/develop/pythonsdk/model/message.md new file mode 100644 index 00000000..edafa38b --- /dev/null +++ b/docs/develop/pythonsdk/model/message.md @@ -0,0 +1,80 @@ +# 消息对象(Message) + +## Message + +| 字段名 | 类型 | 描述 | +| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 id | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| edited_timestamp | string | 消息编辑时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| mention_everyone | boolean | 是否是@全员消息 | +| author | [User](/user#user) | 消息创建者 | +| attachments | [MessageAttachment[]](#messageattachment) | 附件 | +| embeds | [MessageEmbed[]](#messageembed) | embed | +| mentions | [User](/user#user) | 消息中@的人 | +| member | [Member](d#member) | 消息创建者的 member 信息 | +| ark | [MessageArk](#messageark) | ark 消息 | + +## MessageToCreate + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息体 | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +## MessageAttachment + +| 字段名 | 类型 | 描述 | +| ------ | ------ | -------- | +| url | string | 下载地址 | + +## MessageArk + +| 字段名 | 类型 | 描述 | +| :---------- | :------------------------------ | :------------------------ | +| template_id | number | ark 模板 id（需要先申请） | +| kv | [MessageAkrKv[]](#messagearkkv) | kv 值列表 | + +## MessageArkKv + +| 字段名 | 类型 | 描述 | +| :----- | :-------------------------------- | :----------------- | +| key | string | key | +| value | string | value | +| obj | [MessageArkObj[]](#messagearkobj) | ark obj 类型的列表 | + +## MessageArkObj + +| 字段名 | 类型 | 描述 | +| :----- | :--------------------------------- | :------------- | +| obj_kv | [MessageArkObjKv[]](#messageobjkv) | ark objkv 列表 | + +## MessageArkObjKv + +| 字段名 | 类型 | 描述 | +| :----- | :----- | :---- | +| key | string | key | +| value | string | value | diff --git a/docs/develop/pythonsdk/model/role.md b/docs/develop/pythonsdk/model/role.md new file mode 100644 index 00000000..fa5efa2e --- /dev/null +++ b/docs/develop/pythonsdk/model/role.md @@ -0,0 +1,21 @@ +# 频道身份组对象(Role) + +### Role + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +### DefaultRoleIDs(系统默认生成下列身份组 ID) + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | diff --git a/docs/develop/pythonsdk/model/user.md b/docs/develop/pythonsdk/model/user.md new file mode 100644 index 00000000..576c2930 --- /dev/null +++ b/docs/develop/pythonsdk/model/user.md @@ -0,0 +1,14 @@ +# 用户对象(User) + +用户对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +## User + +| 字段名 | 类型 | 描述 | +| ------------------ | ------ | -------------------------------------------------------------------------------------------------- | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | +| union_openid | string | 特殊关联应用的 openid，需要特殊申请并配置后才会返回。如需申请，请联系平台运营人员。 | +| union_user_account | string | 机器人关联的互联应用的用户信息，与 union_openid 关联的应用是同一个。如需申请，请联系平台运营人员。 | diff --git a/docs/develop/pythonsdk/websocket/listen_events.md b/docs/develop/pythonsdk/websocket/listen_events.md new file mode 100644 index 00000000..dfef91e4 --- /dev/null +++ b/docs/develop/pythonsdk/websocket/listen_events.md @@ -0,0 +1,76 @@ +# WSS 消息体 + +## 当前支持的事件类型 + +```python +class HandlerType(Enum): + PLAIN_EVENT_HANDLER = 0 # 透传事件 + GUILD_EVENT_HANDLER = 1 # 频道事件 + GUILD_MEMBER_EVENT_HANDLER = 2 # 频道成员事件 + CHANNEL_EVENT_HANDLER = 3 # 子频道事件 + MESSAGE_EVENT_HANDLER = 4 # 消息事件 + AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 +``` + +## 当前支持的事件 + +```python +class WsEvent: + EventGuildCreate = "GUILD_CREATE" + EventGuildUpdate = "GUILD_UPDATE" + EventGuildDelete = "GUILD_DELETE" + + EventChannelCreate = "CHANNEL_CREATE" + EventChannelUpdate = "CHANNEL_UPDATE" + EventChannelDelete = "CHANNEL_DELETE" + + EventGuildMemberAdd = "GUILD_MEMBER_ADD" + EventGuildMemberUpdate = "GUILD_MEMBER_UPDATE" + EventGuildMemberRemove = "GUILD_MEMBER_REMOVE" + + EventMessageCreate = "MESSAGE_CREATE" + + EventAtMessageCreate = "AT_MESSAGE_CREATE" +``` + +## 当前事件的返回类型 + +``` py +#透传事件（无具体的数据对象，根据后台返回Json对象） +def _plain_handler(event, data): +#频道事件 +def _guild_handler(event, guild:Guild): +#频道成员事件 +def _guild_member_handler(event, guild_member: GuildMember): +#子频道事件 +def _channel_handler(event, channel: Channel): +#消息事件 +def _message_handler(event, message: Message): +#At消息事件 +def _message_handler(event, message: Message): +``` + +## 使用示例 + +### 创建 WSS 实例并监听消息 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + + +def _message_handler(event, message: Message): + msg_api = qqbot.MessageAPI(t_token, False) + # 打印返回信息 + qqbot.logger.info("event %s" % event + ",receive message %s" % message.content) + # 构造消息发送请求数据对象 + send = qqbot.MessageSendRequest("<@%s>谢谢你，加油" % message.author.id, message.id) + # 通过api发送回复消息 + msg_api.post_message(message.channel_id, send) + + +qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) +qqbot.listen_events(token, False, qqbot_handler) +``` +