shkong/OpenShamrock
1
0
Fork 0
mirror of https://github.com/whitechi73/OpenShamrock.git synced 2024-08-14 13:12:17 +08:00
Code Issues Packages Projects Releases Wiki Activity
OpenShamrock/docs/api/guild.md

609 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: 频道相关
icon: user-group
---
::: warning 注意
对于 Shamrock 尚未实现的 API，会在标题添加标记 <Badge text="未实现" type="danger" vertical="baseline" />
:::
## 获取频道系统内BOT的资料
该接口用于获取频道系统内BOT的资料。
### API 端点
`/get_guild_service_profile`
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"nickname": "田所浩二",
"tiny_id": 1145141919810,
"avatar_url": "http://thirdqq.qlogo.cn/g?b=oidb&k=***&kti=***&s=0&t=***"
},
"echo": 123446
}
```
## 获取频道列表
获取频道列表，数据相比于Go-CQHTTP会有一点不一样。
### API 端点
`/get_guild_list`
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"guild_list": [
{
"guild_id": 111111111111111,
"guild_name": "北京大学频道",
"guild_display_id": "abcdefg",
"profile": "北京大学交流频道",
"status": {
"is_enable": true,
"is_banned": false,
"is_frozen": false
},
"owner_id": 22222222222222,
"shutup_expire_time": 0,
"allow_search": true
}
]
},
"message": "success",
"echo": 111
}
```
## 通过访客获取频道元数据
获取频道元数据，例如当前成员数量之类。
### API 端点
`/get_guild_meta_by_guest`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | ------ |
| guild_id | uint64 | 频道ID |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"guild_id": 11111111111,
"guild_name": "北京大学交流频道",
"guild_profile": "",
"create_time": 1606878500,
"max_member_count": 100000,
"max_robot_count": 100,
"max_admin_count": 50,
"member_count": 6241,
"owner_id": 2222222221,
"guild_display_id": ""
},
"echo": 111
}
```
## 获取子频道列表
获取一个频道的子频道(channel)列表。
### API 端点
`/get_guild_channel_list`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | ------------------------- |
| guild_id | uint64 | 频道ID |
| refresh | bool | 是否刷新数据，默认`false` |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"channel_list": [
{
"owner_guild_id": 1111111111111111111,
"channel_id": 639093000,
"channel_uin": 639093000,
"guild_id": "1111111111111111111",
"channel_type": 2,
"channel_name": "Test",
"create_time": 1606879350,
"max_member_count": 99,
"creator_tiny_id": 124105218677239793,
"talk_permission": 1,
"visible_type": 1,
"current_slow_mode": 0,
"slow_modes": [],
"icon_url": "",
"jump_switch": 0,
"jump_type": 0,
"jump_url": "",
"category_id": 0,
"my_talk_permission": 2
},
{
"owner_guild_id": 1111111111111111111,
"channel_id": 639093001,
"channel_uin": 639093001,
"guild_id": "1111111111111111111",
"channel_type": 1,
"channel_name": "闲聊吹水",
"create_time": 1606878501,
"max_member_count": 0,
"creator_tiny_id": 124105218677239793,
"talk_permission": 1,
"visible_type": 1,
"current_slow_mode": 0,
"slow_modes": [
{
"slow_mode_key": 0,
"slow_mode_text": "关闭",
"speak_frequency": 0,
"slow_mode_circle": 0
},
{
"slow_mode_key": 1,
"slow_mode_text": "每分钟1条",
"speak_frequency": 1,
"slow_mode_circle": 60
},
{
"slow_mode_key": 2,
"slow_mode_text": "每分钟2条",
"speak_frequency": 2,
"slow_mode_circle": 60
},
{
"slow_mode_key": 3,
"slow_mode_text": "每分钟5条",
"speak_frequency": 5,
"slow_mode_circle": 60
},
{
"slow_mode_key": 4,
"slow_mode_text": "每分钟10条",
"speak_frequency": 10,
"slow_mode_circle": 60
},
{
"slow_mode_key": 5,
"slow_mode_text": "每5分钟1条",
"speak_frequency": 1,
"slow_mode_circle": 300
},
{
"slow_mode_key": 6,
"slow_mode_text": "每10分钟1条",
"speak_frequency": 1,
"slow_mode_circle": 600
},
{
"slow_mode_key": 7,
"slow_mode_text": "每15分钟1条",
"speak_frequency": 1,
"slow_mode_circle": 900
},
{
"slow_mode_key": 8,
"slow_mode_text": "每30分钟1条",
"speak_frequency": 1,
"slow_mode_circle": 1800
},
{
"slow_mode_key": 9,
"slow_mode_text": "每1小时1条",
"speak_frequency": 1,
"slow_mode_circle": 3600
},
{
"slow_mode_key": 10,
"slow_mode_text": "每12小时1条",
"speak_frequency": 1,
"slow_mode_circle": 43200
},
{
"slow_mode_key": 11,
"slow_mode_text": "每24小时1条",
"speak_frequency": 1,
"slow_mode_circle": 86400
}
],
"icon_url": "",
"jump_switch": 0,
"jump_type": 0,
"jump_url": "",
"category_id": 0,
"my_talk_permission": 2
}
]
},
"message": "success",
"echo": 111
}
```
#### 已知子频道类型列表
| 类型 | 说明 |
| ---- | -------- |
| 1 | 文字频道 |
| 2 | 语音频道 |
| 5 | 直播频道 |
| 7 | 主题频道 |
## 获取频道成员列表
获取一个频道成员列表，但是因为数据量大，可能需要分页。
### API 端点
`/get_guild_member_list`
### 参数
| 字段 | 类型 | 说明 |
| ---------- | ------ | ------------------------------------- |
| guild_id | uint64 | 频道ID |
| next_token | string | 不提供则从首页开始获取 |
| all | bool | 是否一次性获取完所有成员，默认`false` |
| refresh | bool | 是否刷新数据，默认`false` |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"members": [
{
"tiny_id": 144115218185291865,
"title": "频道助手",
"nickname": "频道助手",
"role_id": 2,
"role_name": "小管家",
"role_color": 4294936110,
"join_time": 1606878501,
"robot_type": 1,
"type": 1,
"in_black": false,
"platform": 0
}
],
"next_token": "0800100118032001",
"finished": true
},
"echo": ""
}
```
## 单独获取频道成员资料
单独获取频道成员信息，附带有权限信息和身份组哦~！
### API 端点
`/get_guild_member_profile`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | ------------ |
| guild_id | uint64 | 频道ID |
| user_id | uint64 | 成员`tinyId` |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"tiny_id": 123456,
"nickname": "***",
"avatar_url": "https://qqchannel-profile-1251316161.file.myqcloud.com/***",
"join_time": 1606878500,
"roles": [
{
"role_id": "4",
"role_name": "频道主",
"color": 4294917938,
"permission": [
{
"root_id": 10000,
"child_ids": [10001, 10002, 10003, 10004, 10005]
},
{
"root_id": 20000,
"child_ids": [
20001, 20002, 20003, 20004, 20005, 20006, 20007, 20008, 20009, 20010, 20011, 20012,
20013, 20014, 20015, 20018, 20019
]
},
{
"root_id": 30000,
"child_ids": [30001, 30002, 30003, 30004, 30005, 30006, 30007, 90002]
},
{
"root_id": 40000,
"child_ids": [40001, 40002]
},
{
"root_id": 50000,
"child_ids": [50001]
},
{
"root_id": 60000,
"child_ids": [60001]
},
{
"root_id": 70000,
"child_ids": [70001, 70002, 70003, 70004, 70005, 70006, 70007]
},
{
"root_id": 80000,
"child_ids": [80001, 80002]
},
{
"root_id": 90000,
"child_ids": [90001, 30003]
},
{
"root_id": 100000,
"child_ids": [100001, 100002]
},
{
"root_id": 1,
"child_ids": [1001, 1002, 1003, 1004, 1005]
},
{
"root_id": 2,
"child_ids": [
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
2015, 2016, 2017, 2018
]
},
{
"root_id": 3,
"child_ids": [3001, 3002, 3003, 3004, 3005, 3006]
},
{
"root_id": 4,
"child_ids": [4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008]
},
{
"root_id": 5,
"child_ids": [5001]
},
{
"root_id": 6,
"child_ids": [6001, 6002, 6003]
}
],
"type": 0,
"display_name": "频道主"
},
{
"role_id": "15",
"role_name": "15活跃值",
"color": 4278190080,
"permission": [],
"type": 100,
"display_name": ""
}
]
},
"echo": 111
}
```
## 发送信息到子频道
发送频道内信息，需要单独的API哦，不要使用`/send_message`去发频道消息，发不出去的~~
### API 端点
`/send_guild_channel_msg`
### 参数
| 字段 | 类型 | 说明 |
| --------------- | ------------------- | ----------------------------------------- |
| guild_id | uint64 | 频道ID |
| channel_id | uint64 | 子频道ID |
| message | string or `Message` | 消息体，可为消息段或者CQ码 |
| auto_escape | bool | 是否解析CQ码，`true`为不解析，默认`false` |
| retry_cnt | int32 | 消息发送失败，最大重试次数，默认`3` |
| recall_duration | int64 | 自动撤回间隔(毫秒)，默认不撤回 |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"message_id": 1933593189,
"time": 1706909190
},
"echo": 111
}
```
## 获取话题频道帖子
该API接口已经被遗弃！
## 获取频道帖子广场帖子
新的获取帖子广场的帖子哦！
### API 端点
`/get_guild_feeds`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | -------------- |
| guild_id | uint64 | 频道ID |
| from | uint32 | 开始获取的位置 |
### 响应示例
> 该请求携带了大量原生响应数据，无法详细介绍，请自行测试！
## 获取频道角色列表
获取身份组列表，包括隐藏的身份组哦~~
### API 端点
`/get_guild_roles`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | ------ |
| guild_id | uint64 | 频道ID |
### 响应示例
```json
{
"status": "ok",
"retcode": 0,
"data": {
"roles": [
{
"argb_color": 4286151052,
"disabled": false,
"independent": false,
"max_count": 1000,
"member_count": 0,
"owned": false,
"role_id": 1,
"role_name": "普通成员",
"permission": []
}
]
},
"echo": 111
}
```
## 获取频道消息
该接口不会实现，因为您可以调用`/get_msg`来获取来自频道的消息，无需实现一个专属的接口。
## 删除频道角色
删除一个身份组，首先，你得保证你有权限，因为这个API不会提供任何返回数据哦！
### API 端点
`/delete_guild_role`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | ------ |
| guild_id | uint64 | 频道ID |
| role_id | uint64 | 角色ID |
### 响应
> 该 API 无响应数据
## 设置用户在频道中的角色
设置用户身份组。
### API端点
`/set_guild_member_role`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------------------------- | ------------------------- |
| guild_id | uint64 | 频道ID |
| role_id | uint64 | 角色ID |
| set | bool | 设置还是移除，默认`false` |
| users | string or `vector<int64>` | 批量设置用户s |
| user_id | int64 | 单独设置某个用户的身份 |
> 如果users是字符串那么其格式为`123456,6656656526,2652656`，以逗号分隔每个`tinyId`。
## 修改频道角色
修改频道角色，暂不支持设置权限，如有需要请提交`issue`。
### API 端点
`/update_guild_role`
### 参数
| 字段 | 类型 | 说明 |
| -------- | ------ | -------- |
| guild_id | uint64 | 频道ID |
| role_id | uint64 | 角色ID |
| name | string | 名称 |
| color | int64 | 颜色ARGB |
### 响应
> 该 API 无响应数据
## 创建频道角色
创建频道身份组。
### API 端点
`/create_guild_role`
### 参数
| 字段 | 类型 | 说明 |
| ------------- | --------------- | -------------- |
| guild_id | uint64 | 频道ID |
| name | string | 名称 |
| color | int64 | 颜色ARGB |
| initial_users | `vector<int64>` | 默认身份组成员 |
> 如果是`HTTP`请求，则`initial_users`使用字符串，以`,`为用户`tiny_id`分隔。
### 响应
| 字段 | 类型 | 说明 |
| ------- | ------ | ------ |
| role_id | uint64 | 角色ID |
Reference in New Issue View Git Blame Copy Permalink