diff --git a/LICENSE b/LICENSE
index 2a35213..05531e7 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2020 backend
+Copyright (c) 2020-2024 KOOK official and contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/docs/zh-cn/http/guild.md b/docs/zh-cn/http/guild.md
index 4409022..ebe3f78 100644
--- a/docs/zh-cn/http/guild.md
+++ b/docs/zh-cn/http/guild.md
@@ -4,61 +4,71 @@
本文档中的接口均符合接口规范，如有疑问，建议先查阅[接口引言](https://developer.kookapp.cn/doc/reference)。
-| 接口 | 接口说明 | 维护状态 |
-| --------------------------------------------------- | ---------------------------- | -------- |
-| [/api/v3/guild/list](#获取当前用户加入的服务器列表) | 获取当前用户加入的服务器列表 | 正常 |
-| [/api/v3/guild/view](#获取服务器详情) | 获取服务器详情 | 正常 |
-| [/api/v3/guild/user-list](#获取服务器中的用户列表) | 获取服务器中的用户列表 | 正常 |
-| [/api/v3/guild/nickname](#修改服务器中用户的昵称) | 修改服务器中用户的昵称 | 正常 |
-| [/api/v3/guild/leave](#离开服务器) | 离开服务器 | 正常 |
-| [/api/v3/guild/kickout](#踢出服务器) | 踢出服务器 | 正常 |
-| [/api/v3/guild-mute/list](#服务器静音闭麦列表) | 服务器静音闭麦列表 | 正常 |
-| [/api/v3/guild-mute/create](#添加服务器静音或闭麦) | 添加服务器静音或闭麦 | 正常 |
-| [/api/v3/guild-mute/delete](#删除服务器静音或闭麦) | 删除服务器静音或闭麦 | 正常 |
-| [/api/v3/guild-boost/history](#服务器助力历史) | 查询服务器的助力包历史 | 正常 |
+| 接口 | 接口说明 | 维护状态 |
+|------------------------------------------|----------------|------|
+| [/api/v3/guild/list](#获取当前用户加入的服务器列表) | 获取当前用户加入的服务器列表 | 正常 |
+| [/api/v3/guild/view](#获取服务器详情) | 获取服务器详情 | 正常 |
+| [/api/v3/guild/user-list](#获取服务器中的用户列表) | 获取服务器中的用户列表 | 正常 |
+| [/api/v3/guild/nickname](#修改服务器中用户的昵称) | 修改服务器中用户的昵称 | 正常 |
+| [/api/v3/guild/leave](#离开服务器) | 离开服务器 | 正常 |
+| [/api/v3/guild/kickout](#踢出服务器) | 踢出服务器 | 正常 |
+| [/api/v3/guild-mute/list](#服务器静音闭麦列表) | 服务器静音闭麦列表 | 正常 |
+| [/api/v3/guild-mute/create](#添加服务器静音或闭麦) | 添加服务器静音或闭麦 | 正常 |
+| [/api/v3/guild-mute/delete](#删除服务器静音或闭麦) | 删除服务器静音或闭麦 | 正常 |
+| [/api/v3/guild-boost/history](#服务器助力历史) | 查询服务器的助力包历史 | 正常 |
## 获取当前用户加入的服务器列表
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| -------------------- | -------- | ---- |
-| `/api/v3/guild/list` | GET | |
+| 地址 | 请求方式 | 说明 |
+|----------------------|------|----|
+| `/api/v3/guild/list` | GET | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| --------- | ----- | ------- | ----- | -------------------------------------------------------------------------------------------------------------------- |
-| page | query | integer | false | 目标页数 |
-| page_size | query | integer | false | 每页数据数量 |
-| sort | query | string | false | 代表排序的字段, 比如-id 代表 id 按 DESC 排序，id 代表 id 按 ASC 排序。不一定有, 如果有，接口中会声明支持的排序字段。 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|-----------|-------|---------|-------|-----------------------------------------------------------------------------------|
+| page | query | integer | false | 目标页数，默认值 `1` |
+| page_size | query | integer | false | 每页数据数量，默认值 `100`，最大值 `100` |
+| sort | query | string | false | 代表排序的字段，及其排序方式
例如：`id` 表示按 `id` 字段升序排序，`-id` 表示按 `id` 字段降序排序
支持排序的字段包括：`id` |
### 返回参数说明
-| 参数名 | 类型 | 说明 |
-| ------------------ | ------- | ------------------------------------------------------------------------------------------------- |
-| id | string | 服务器 id |
-| name | string | 服务器名称 |
-| topic | string | 服务器主题 |
-| user_id | string | 服务器主的 id |
-| icon | string | 服务器 icon 的地址 |
-| notify_type | int | 通知类型, `0`代表默认使用服务器通知设置，`1`代表接收所有通知, `2`代表仅@被提及，`3`代表不接收通知 |
-| region | string | 服务器默认使用语音区域 |
-| enable_open | boolean | 是否为公开服务器 |
-| open_id | string | 公开服务器 id |
-| default_channel_id | string | 默认频道 id |
-| welcome_channel_id | string | 欢迎频道 id |
-| boost_num | integer | 服务器助力数量 |
-| level | integer | 服务器等级 |
+| 参数名 | 类型 | 说明 |
+|--------------------|---------|------------------------------------------------------------------------|
+| id | string | 服务器 ID |
+| name | string | 服务器名称 |
+| topic | string | 服务器主题 |
+| user_id | string | 服务器主用户的 ID |
+| is_master | boolean | 当前用户是否为该服务器的服务器主 |
+| icon | string | 服务器图标地址，若服务器从未设置过图标，则此值为空字符串 |
+| notify_type | int | 服务器默认通知类型，枚举值 `notify_type` 见表后 |
+| region | string | 服务器默认语音区域，枚举值 `region` 见表后 |
+| enable_open | boolean | 是否为公开服务器 |
+| open_id | string | 服务器的公开 ID，若服务器从未设置为公开状态，则此值为 `0` |
+| default_channel_id | string | 服务器默认频道 ID，若服务器的默认文字频道设置为无默认频道，则此值为服务器的首个文字频道的频道 ID，若服务器无文字频道，则此值为 `0` |
+| welcome_channel_id | string | 服务器欢迎通知频道 ID，若服务器的欢迎通知频道设置为无欢迎通知，则此值为 `0` |
#### 枚举值
-| 属性 | 属性值 |
-| ----------- | ------ |
-| notify_type | 0 |
-| notify_type | 1 |
-| notify_type | 2 |
-| notify_type | 3 |
+- `notify_type`
+
+| 属性值 | 说明 |
+|-----|--------|
+| 1 | 接收所有消息 |
+| 2 | 仅@被提及 |
+
+- `region`
+
+| 属性值 | 说明 |
+|----------|------------|
+| chengdu | 西南(成都) |
+| beijing | 华北(北京) |
+| shanghai | 华东(上海) |
+| shenzhen | 华南(深圳) |
+| hk | 亚太(香港) |
+| vnga | 国际专线(助力专享) |
### 返回示例
@@ -79,9 +89,7 @@
"enable_open": true,
"open_id": "012312413",
"default_channel_id": "5915900001396830",
- "welcome_channel_id": "5789900001312330",
- "boost_num": 3,
- "level": 0
+ "welcome_channel_id": "5789900001312330"
}
],
"meta": {
@@ -101,42 +109,70 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| -------------------- | -------- | ---- |
-| `/api/v3/guild/view` | GET | |
+| 地址 | 请求方式 | 说明 |
+|----------------------|------|----|
+| `/api/v3/guild/view` | GET | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| -------- | ----- | ------ | ---- | --------- |
-| guild_id | query | string | true | 服务器 id |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|----------|-------|--------|------|--------|
+| guild_id | query | string | true | 服务器 ID |
### 返回参数说明
-| 参数名 | 类型 | 说明 |
-| ------------------ | ------- | ------------------------------------------------------------------------------------------------- |
-| id | string | 服务器 id |
-| name | string | 服务器名称 |
-| topic | string | 服务器主题 |
-| user_id | string | 服务器主的 id |
-| icon | string | 服务器 icon 的地址 |
-| notify_type | int | 通知类型, `0`代表默认使用服务器通知设置，`1`代表接收所有通知, `2`代表仅@被提及，`3`代表不接收通知 |
-| region | string | 服务器默认使用语音区域 |
-| enable_open | boolean | 是否为公开服务器 |
-| open_id | string | 公开服务器 id |
-| default_channel_id | string | 默认频道 id |
-| welcome_channel_id | string | 欢迎频道 id |
-| roles | array | 角色列表 |
-| channels | array | 频道列表 |
+| 参数名 | 类型 | 说明 |
+|--------------------|------------------------|------------------------------------------------------------------------|
+| id | string | 服务器 ID |
+| name | string | 服务器名称 |
+| topic | string | 服务器主题 |
+| user_id | string | 服务器主用户的 ID |
+| is_master | boolean | 当前用户是否为该服务器的服务器主 |
+| icon | string | 服务器图标地址，若服务器从未设置过图标，则此值为空字符串 |
+| notify_type | int | 服务器默认通知类型，枚举值 `notify_type` 见表后 |
+| region | string | 服务器默认语音区域，枚举值 `region` 见表后 |
+| enable_open | boolean | 是否为公开服务器 |
+| open_id | string | 服务器的公开 ID，若服务器从未设置为公开状态，则此值为 `0` |
+| default_channel_id | string | 服务器默认频道 ID，若服务器的默认文字频道设置为无默认频道，则此值为服务器的首个文字频道的频道 ID，若服务器无文字频道，则此值为 `0` |
+| welcome_channel_id | string | 服务器欢迎通知频道 ID，若服务器的欢迎通知频道设置为无欢迎通知，则此值为 `0` |
+| features | array | 服务器特性，数组成员为 `string` 类型，其枚举值 `feature` 见表后 |
+| boost_num | integer | 服务器助力包数量 |
+| buffer_boost_num | integer | 由拥有 BUFF 会员的用户为服务器提供的助力包数量（存疑） |
+| level | integer | 服务器助力等级 |
+| status | integer | TODO |
+| auto_delete_time | string | TODO |
+| recommend_info | object (RecommendInfo) | 服务器推荐信息，当服务器不为推荐服务器时，此字段不存在 |
+| roles | array (Role) | 服务器角色列表，数组成员为表示服务器角色的 `object` |
+| channels | array (Channel) | 服务器频道列表，数组成员为表示服务器频道的 `object` |
+| user_config | object | 当前用户在该服务器的配置 |
#### 枚举值
-| 属性 | 属性值 |
-| ----------- | ------ |
-| notify_type | 0 |
-| notify_type | 1 |
-| notify_type | 2 |
-| notify_type | 3 |
+- `notify_type`
+
+| 属性值 | 说明 |
+|-----|--------|
+| 1 | 接收所有消息 |
+| 2 | 仅@被提及 |
+
+- `region`
+
+| 属性值 | 说明 |
+|----------|------------|
+| chengdu | 西南(成都) |
+| beijing | 华北(北京) |
+| shanghai | 华东(上海) |
+| shenzhen | 华南(深圳) |
+| hk | 亚太(香港) |
+| vnga | 国际专线(助力专享) |
+
+- `feature`
+
+| 属性值 | 说明 |
+|----------|---------|
+| official | 官方服务器 |
+| partner | 合作伙伴服务器 |
+| ka | 重要客户服务器 |
### 返回示例
@@ -145,45 +181,110 @@
"code": 0,
"message": "操作成功",
"data": {
- "roles": [
- {
- "role_id": 702,
- "name": "管理员",
- "color": 0,
- "position": 1,
- "hoist": 0,
- "mentionable": 0,
- "permissions": 2048
- }
- ],
- "channels": [
- {
- "id": 123,
- "guild_id": "91686000000",
- "user_id": "2418200000",
- "parent_id": 123,
- "name": "测试频道",
- "topic": "频道简介",
- "type": 1,
- "level": 10,
- "slow_mode": 0,
- "is_category": false
- }
- ],
- "id": "91686000000",
- "name": "Hello",
- "topic": "string",
- "user_id": "2418200000",
- "icon": "https://xxx/icons/2020-05/YQyfHxxx.png/icon",
- "notify_type": 0,
- "region": "beijing",
+ "id": "35420000000000000",
+ "name": "服务器名称",
+ "topic": "",
+ "user_id": "2298765067",
+ "is_master": false,
+ "icon": "https://img.kookapp.cn/icons/2022-04/xxxx.gif",
+ "notify_type": 2,
+ "region": "shanghai",
"enable_open": true,
- "open_id": "012312413",
- "default_channel_id": "5915900001396830",
- "welcome_channel_id": "5789900001312330",
- "boost_num": 3,
- "level": 0
- }
+ "open_id": "16900000",
+ "default_channel_id": "7600000000000",
+ "welcome_channel_id": "6100000000000",
+ "features": [
+ "official"
+ ],
+ "boost_num": 100,
+ "buffer_boost_num": 5,
+ "level": 1,
+ "status": 0,
+ "auto_delete_time": "",
+ "recommend_info": {
+ "guild_id": "3542195235225538",
+ "open_id": "16975053",
+ "enable_open": 1,
+ "default_channel_id": "7619070122429812",
+ "name": "「KOOK」活动中心",
+ "icon": "https://img.kookapp.cn/icons/2022-04/Sr1nKh3p0t050050.gif?x-oss-process=style/icon",
+ "banner": "https://img.kaiheila.cn/assets/2022-06/l0uMPxcFf00ls0cs.png?x-oss-process=style/ld",
+ "banner_preview": "https://img.kaiheila.cn/assets/2022-06/l0uMPxcFf00ls0cs.png?x-oss-process=style/preview",
+ "desc": "KOOK官方服务器，帮助大家解决使用KOOK时遇到的问题，还有各种有趣的活动哦~",
+ "status": 1,
+ "guild_status": 0,
+ "tag": "其他社群",
+ "features": [
+ "official",
+ "ka"
+ ],
+ "certifications": [
+ {
+ "type": 1,
+ "title": "KOOK官方服务器",
+ "pic": "https://img.kookapp.cn/assets/2023-12/fR650xKxiF0ew0ew.jpg",
+ "desc": ""
+ }
+ ],
+ "level": 6,
+ "custom_id": "kook",
+ "is_official_partner": 1,
+ "sort": 9999,
+ "gradient": {
+ "id": 4,
+ "color_map": [
+ "0x487796",
+ "0x3E1A1F"
+ ],
+ "limit": 5,
+ "theme": "dark"
+ },
+ "audit_status": 1,
+ "update_day_gap": 0
+ }
+ },
+ "roles": [
+ {
+ "role_id": 100,
+ "name": "管理员",
+ "desc": "描述",
+ "color": 15844367,
+ "color_type": 1,
+ "color_map": {
+ "color_list": [
+ 15627601,
+ 15391536
+ ]
+ },
+ "position": 1,
+ "hoist": 0,
+ "mentionable": 0,
+ "permissions": 134217729,
+ "type": 0
+ }
+ ],
+ "channels": [
+ {
+ "id": "490000000000",
+ "guild_id": "800000000000",
+ "master_id": "2800000000",
+ "parent_id": "520000000000",
+ "user_id": "2800000000",
+ "name": "频道名称",
+ "topic": "频道说明",
+ "type": 1,
+ "level": 4,
+ "slow_mode": 0,
+ "last_msg_content": "内容",
+ "last_msg_id": "2e1bffb6-0000-0000-0000-000000000000",
+ "has_password": false,
+ "limit_amount": 0,
+ "is_category": false,
+ "permission_sync": 1,
+ "permission_overwrites": [],
+ "permission_users": []
+ }
+ ]
}
```
@@ -191,47 +292,49 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| ------------------------- | -------- | ---- |
-| `/api/v3/guild/user-list` | GET | |
+| 地址 | 请求方式 | 说明 |
+|---------------------------|------|----|
+| `/api/v3/guild/user-list` | GET | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| --------------- | ----- | ------- | ----- | ---------------------------------------------- |
-| guild_id | query | string | true | 服务器 id |
-| channel_id | query | string | false | 频道 id |
-| search | query | string | false | 搜索关键字，在用户名或昵称中搜索 |
-| role_id | query | integer | false | 角色 ID，获取特定角色的用户列表 |
-| mobile_verified | query | integer | false | 只能为`0`或`1`，`0`是未认证，`1`是已认证 |
-| active_time | query | integer | false | 根据活跃时间排序，`0`是顺序排列，`1`是倒序排列 |
-| joined_at | query | integer | false | 根据加入时间排序，`0`是顺序排列，`1`是倒序排列 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|-----------------|-------|---------|-------|--------------------------------------------|
+| guild_id | query | string | true | 服务器 ID |
+| channel_id | query | string | false | 频道 ID，如果指定，则获取可见该频道的用户 |
+| search | query | string | false | 搜索关键字，如果指定，则获取用户名或昵称包含该关键字，或用户 ID 为该关键字的用户 |
+| role_id | query | integer | false | 角色 ID，如果指定，则获取具有该角色的用户 |
+| mobile_verified | query | integer | false | 是否已认证手机号码，枚举值 `mobile_verified` 见表后 |
+| active_time | query | integer | false | 根据活跃时间排序，枚举值 `sort` 见表后 |
+| joined_at | query | integer | false | 根据加入时间排序，枚举值 `sort` 见表后 |
| page | query | integer | false | 目标页数 |
-| page_size | query | integer | false | 每页数据数量 |
-| filter_user_id | query | string | false | 获取指定 id 所属用户的信息 |
+| page_size | query | integer | false | 每页数据数量 |
+| filter_user_id | query | string | false | 获取拥有指定用户 ID 的用户的信息 |
#### 枚举值
-| 参数 | 参数值 |
-| --------------- | ------ |
-| mobile_verified | 0 |
-| mobile_verified | 1 |
+- `mobile_verified`
-### 返回参数说明
+| 属性值 | 说明 |
+|-----|-----|
+| 0 | 未认证 |
+| 1 | 已认证 |
-| 参数名 | 类型 | 说明 |
-| ------------- | ------------ | ------------ |
-| user_count | int | 用户数量 |
-| online_count | int | 在线用户数量 |
-| offline_count | int | 离线用户数量 |
-| items | array (User) | 用户列表 |
+- `sort`
-#### 枚举值
+| 属性值 | 说明 |
+|-----|----|
+| 0 | 升序 |
+| 1 | 降序 |
+
+### 返回参数说明
-| 属性 | 属性值 |
-| ------ | ------ |
-| status | 0 |
-| status | 10 |
+| 参数名 | 类型 | 说明 |
+|---------------|-------------------|---------------------|
+| items | array (GuildUser) | 服务器用户列表 |
+| user_count | int | 服务器总用户数量 |
+| online_count | int | 符合筛选条件的所有用户中的在线用户数量 |
+| offline_count | int | 符合筛选条件的所有用户中的离线用户数量 |
### 返回示例
@@ -243,15 +346,24 @@
"items": [
{
"id": "2418200000",
- "username": "tz-un",
- "identify_num": "5618",
- "online": false,
- "status": 0,
+ "username": "用户名",
+ "nickname": "昵称",
+ "identify_num": "1234",
+ "online": true,
"bot": false,
- "avatar": "https://img.kookapp.cn/avatars/2020-02/xxxx.jpg/icon",
- "vip_avatar": "https://img.kookapp.cn/avatars/2020-02/xxxx.jpg/icon",
- "nickname": "tz-unn",
- "roles": [702]
+ "status": 0,
+ "banner": "",
+ "avatar": "https://img.kookapp.cn/assets/2022-01/OpoNctfPgt334334.png?x-oss-process=style/icon",
+ "vip_avatar": "https://img.kookapp.cn/assets/2022-01/OpoNctfPgt334334.png?x-oss-process=style/icon",
+ "mobile_verified": true,
+ "joined_at": 1671000000000,
+ "active_time": 1721000000000,
+ "roles": [
+ 123456
+ ],
+ "is_master": false,
+ "abbr": "",
+ "color": 0
}
],
"meta": {
@@ -274,25 +386,21 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| ------------------------ | -------- | ---- |
-| `/api/v3/guild/nickname` | POST | |
+| 地址 | 请求方式 | 说明 |
+|--------------------------|------|----|
+| `/api/v3/guild/nickname` | POST | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| -------- | ---- | ------ | ----- | ----------------------------------------------------- |
-| guild_id | body | string | true | 服务器的 ID |
-| nickname | body | string | false | 昵称，2 - 64 长度，不传则清空昵称 |
-| user_id | body | string | false | 要修改昵称的目标用户 ID，不传则修改当前登陆用户的昵称 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|----------|------|--------|-------|---------------------------------------------|
+| guild_id | body | string | true | 服务器 ID |
+| nickname | body | string | false | 要设置的昵称，长度 2 至 64 个字符，空字符串、`null`、或不传均表示清空昵称 |
+| user_id | body | string | false | 要修改昵称的目标用户的 ID，空字符串、`null`、或不传均表示当前登陆的用户 |
### 返回参数说明
-| 名称 | 类型 | 必需 | 限制 | 说明 |
-| --------- | ------- | ----- | ---- | ------------------------------------------------------------- |
-| » code | integer | true | none | 错误码，0 代表成功，非 0 代表失败，具体的错误码参见错误码一览 |
-| » message | string | true | none | 错误消息，具体的返回消息会根据 Accept-Language 来返回。 |
-| » data | object | false | none | 返回数据 |
+无
### 返回示例
@@ -308,23 +416,19 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| --------------------- | -------- | ---- |
-| `/api/v3/guild/leave` | POST | |
+| 地址 | 请求方式 | 说明 |
+|-----------------------|------|----|
+| `/api/v3/guild/leave` | POST | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| -------- | ---- | ------ | ---- | --------- |
-| guild_id | body | string | true | 服务器 id |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|----------|------|--------|------|--------|
+| guild_id | body | string | true | 服务器 ID |
### 返回参数说明
-| 名称 | 类型 | 必需 | 限制 | 说明 |
-| --------- | ------- | ----- | ---- | ------------------------------------------------------------- |
-| » code | integer | true | none | 错误码，0 代表成功，非 0 代表失败，具体的错误码参见错误码一览 |
-| » message | string | true | none | 错误消息，具体的返回消息会根据 Accept-Language 来返回。 |
-| » data | object | false | none | 返回数据 |
+无
### 返回示例
@@ -340,24 +444,20 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| ----------------------- | -------- | ---- |
-| `/api/v3/guild/kickout` | POST | |
+| 地址 | 请求方式 | 说明 |
+|-------------------------|------|----|
+| `/api/v3/guild/kickout` | POST | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| --------- | ---- | ------ | ---- | ----------- |
-| guild_id | body | string | true | 服务器 ID |
-| target_id | body | string | true | 目标用户 ID |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|-----------|------|--------|------|---------------|
+| guild_id | body | string | true | 服务器 ID |
+| target_id | body | string | true | 要踢出服务器的用户的 ID |
### 返回参数说明
-| 名称 | 类型 | 必需 | 限制 | 说明 |
-| --------- | ------- | ----- | ---- | ------------------------------------------------------------- |
-| » code | integer | true | none | 错误码，0 代表成功，非 0 代表失败，具体的错误码参见错误码一览 |
-| » message | string | true | none | 错误消息，具体的返回消息会根据 Accept-Language 来返回。 |
-| » data | object | false | none | 返回数据 |
+无
### 返回示例
@@ -373,25 +473,35 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| ------------------------- | -------- | ---- |
-| `/api/v3/guild-mute/list` | GET | |
+| 地址 | 请求方式 | 说明 |
+|---------------------------|------|----|
+| `/api/v3/guild-mute/list` | GET | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| ----------- | ----- | ------ | ----- | -------------------------------------------- |
-| guild_id | query | string | true | 服务器 id |
-| return_type | query | string | false | 返回格式，建议为"detail", 其他情况仅作为兼容 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|-------------|-------|--------|-------|------------------------------|
+| guild_id | query | string | true | 服务器 ID |
+| return_type | query | string | false | 返回格式，建议为 `detail`, 其他情况仅作为兼容 |
### 返回参数说明
返回格式中，type 值,`1`代表麦克风闭麦，`2`代表耳机静音。
+| 名称 | 类型 | 说明 |
+|------------|---------|-----------------|
+| mic | object | 服务器闭麦信息 |
+| - type | integer | 值为 `1` |
+| - user_ids | array | 所有被服务器闭麦的用户的 ID |
+| headset | object | 服务器静音信息 |
+| - type | integer | 值为 `2` |
+| - user_ids | array | 所有被服务器静音的用户的 ID |
+
### 返回示例
+参数 `return_typ` 为 `detail`
+
```json
-# 请设置return_typ为detail
{
"code": 0,
"message": "操作成功",
@@ -416,17 +526,26 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| --------------------------- | -------- | ---- |
-| `/api/v3/guild-mute/create` | POST | |
+| 地址 | 请求方式 | 说明 |
+|-----------------------------|------|----|
+| `/api/v3/guild-mute/create` | POST | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| -------- | ---- | ------ | ---- | -------------------------------------------- |
-| guild_id | body | string | true | 服务器 id |
-| user_id | body | string | true | 目标用户 id |
-| type | body | int | true | 静音类型，`1`代表麦克风闭麦，`2`代表耳机静音 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|----------|------|--------|------|---------------------|
+| guild_id | body | string | true | 服务器 ID |
+| user_id | body | string | true | 目标用户 ID |
+| type | body | int | true | 静音类型，枚举值 `type` 见表后 |
+
+#### 枚举值
+
+- `type`
+
+| 属性值 | 说明 |
+|-----|-------|
+| 1 | 麦克风闭麦 |
+| 2 | 耳机静音 |
### 返回参数说明
@@ -446,17 +565,26 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| --------------------------- | -------- | ---- |
-| `/api/v3/guild-mute/delete` | POST | |
+| 地址 | 请求方式 | 说明 |
+|-----------------------------|------|----|
+| `/api/v3/guild-mute/delete` | POST | |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| -------- | ---- | ------ | ---- | -------------------------------------------- |
-| guild_id | body | string | true | 服务器 id |
-| user_id | body | string | true | 用户 id |
-| type | body | int | true | 静音类型，`1`代表麦克风闭麦，`2`代表耳机静音 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|----------|------|--------|------|---------------------|
+| guild_id | body | string | true | 服务器 ID |
+| user_id | body | string | true | 目标用户 ID |
+| type | body | int | true | 静音类型，枚举值 `type` 见表后 |
+
+#### 枚举值
+
+- `type`
+
+| 属性值 | 说明 |
+|-----|-------|
+| 1 | 麦克风闭麦 |
+| 2 | 耳机静音 |
### 返回参数说明
@@ -476,29 +604,29 @@
### 接口说明
-| 地址 | 请求方式 | 说明 |
-| ----------------------------- | -------- | ------------------- |
-| `/api/v3/guild-boost/history` | GET | 需要有`服务器管理`权限 |
+| 地址 | 请求方式 | 说明 |
+|-------------------------------|------|--------------|
+| `/api/v3/guild-boost/history` | GET | 需要有`管理服务器`权限 |
### 参数列表
-| 参数名 | 位置 | 类型 | 必需 | 说明 |
-| ---------- | ----- | ------ | ----- | --------------------------- |
-| guild_id | query | string | true | 服务器 id |
-| start_time | query | int | false | unix 时间戳，时间范围的开始时间 |
-| end_time | query | int | false | unix 时间戳，时间范围的结束时间 |
+| 参数名 | 位置 | 类型 | 必需 | 说明 |
+|------------|-------|--------|-------|----------------------------------|
+| guild_id | query | string | true | 服务器 ID |
+| start_time | query | int | false | Unix 秒时间戳，如果指定，则获取生效时间不早于该时间的助力包 |
+| end_time | query | int | false | Unix 秒时间戳，如果指定，则获取生效时间不晚于该时间的助力包 |
### 返回参数说明
返回格式为标准分页格式，以 `start_time` 由大到小排列，其中 `items` 数据如下：
-| 名称 | 类型 | 说明 |
-| ---------- | ------ | -------------------------------- |
-| user_id | string | 使用助力包的用户 ID |
-| guild_id | string | 服务器的 ID |
-| start_time | int | 助力包生效时间, Unix 时间戳 (单位: 秒)|
-| end_time | int | 助力包失效时间, Unix 时间戳 (单位: 秒)|
-| user | object | 使用助力包的用户数据对象 |
+| 名称 | 类型 | 说明 |
+|------------|--------------------|--------------------|
+| user_id | string | 使用助力包的用户 ID |
+| guild_id | string | 服务器的 ID |
+| start_time | int | 助力包生效时间, Unix 秒时间戳 |
+| end_time | int | 助力包失效时间, Unix 秒时间戳 |
+| user | object (GuildUser) | 使用助力包的服务器用户 |
### 返回示例
@@ -519,11 +647,25 @@
"identify_num": "0000",
"online": false,
"os": "Websocket",
- "avatar": "",
- "vip_avatar": "",
- "banner": "",
- "nickname": "XXXX",
- "bot": false
+ "status": 1,
+ "avatar": "https://img.kookapp.cn/avatars/2021-07/xxxxxxxxxxxxx.png",
+ "vip_avatar": "https://img.kookapp.cn/avatars/2021-07/xxxxxxxxxxx.png",
+ "banner": "https://img.kookapp.cn/assets/2022-06/xxxxxxxxx.png",
+ "nickname": "XXX",
+ "roles": [],
+ "is_vip": true,
+ "vip_amp": true,
+ "bot": false,
+ "nameplate": [],
+ "decorations_id_map": {
+ "join_voice": 10000,
+ "background": 10000,
+ "nameplate": 10000,
+ "nameplates": [
+ 10000
+ ]
+ },
+ "is_sys": false
}
}
],
diff --git a/docs/zh-cn/objects.md b/docs/zh-cn/objects.md
index 292adc9..0b6107d 100644
--- a/docs/zh-cn/objects.md
+++ b/docs/zh-cn/objects.md
@@ -4,19 +4,19 @@
## 用户 User
-| 参数名 | 类型 | 说明 |
-| --------------- | ------- | ------------------------------------------------------ |
-| id | string | 用户的 id |
-| username | string | 用户的名称 |
-| nickname | string | 用户在当前服务器的昵称 |
+| 参数名 | 类型 | 说明 |
+|-----------------|---------|----------------------------------------|
+| id | string | 用户的 id |
+| username | string | 用户的名称 |
+| nickname | string | 用户在当前服务器的昵称 |
| identify_num | string | 用户名的认证数字，用户名正常为：user_name#identify_num |
-| online | boolean | 当前是否在线 |
-| bot | boolean | 是否为机器人 |
+| online | boolean | 当前是否在线 |
+| bot | boolean | 是否为机器人 |
| status | int | 用户的状态, 0 和 1 代表正常，10 代表被封禁 |
-| avatar | string | 用户的头像的 url 地址 |
-| vip_avatar | string | vip 用户的头像的 url 地址，可能为 gif 动图 |
-| mobile_verified | boolean | 是否手机号已验证 |
-| roles | Array | 用户在当前服务器中的角色 id 组成的列表 |
+| avatar | string | 用户的头像的 url 地址 |
+| vip_avatar | string | vip 用户的头像的 url 地址，可能为 gif 动图 |
+| mobile_verified | boolean | 是否手机号已验证 |
+| roles | Array | 用户在当前服务器中的角色 id 组成的列表 |
**示例**
@@ -41,21 +41,21 @@
## 服务器 Guild
-| 字段 | 类型 | 说明 |
-| ------------------ | ------- | ------------------------------------------------------------------------------------------------- |
-| id | string | 服务器 id |
-| name | string | 服务器名称 |
-| topic | string | 服务器主题 |
-| user_id | string | 服务器主的 id |
-| icon | string | 服务器 icon 的地址 |
+| 字段 | 类型 | 说明 |
+|--------------------|---------|-----------------------------------------------------------|
+| id | string | 服务器 id |
+| name | string | 服务器名称 |
+| topic | string | 服务器主题 |
+| user_id | string | 服务器主的 id |
+| icon | string | 服务器 icon 的地址 |
| notify_type | int | 通知类型, `0`代表默认使用服务器通知设置，`1`代表接收所有通知, `2`代表仅@被提及，`3`代表不接收通知 |
-| region | string | 服务器默认使用语音区域 |
-| enable_open | boolean | 是否为公开服务器 |
-| open_id | string | 公开服务器 id |
-| default_channel_id | string | 默认频道 id |
-| welcome_channel_id | string | 欢迎频道 id |
-| roles | array | 角色列表 |
-| channels | array | 频道列表 |
+| region | string | 服务器默认使用语音区域 |
+| enable_open | boolean | 是否为公开服务器 |
+| open_id | string | 公开服务器 id |
+| default_channel_id | string | 默认频道 id |
+| welcome_channel_id | string | 欢迎频道 id |
+| roles | array | 角色列表 |
+| channels | array | 频道列表 |
**示例**
@@ -100,15 +100,15 @@
## 角色 Role
-| 字段 | 类型 | 说明 |
-| ----------- | ------ | ---------------------------------- |
-| role_id | int | 角色 id |
-| name | string | 角色名称 |
-| color | int | 颜色色值 |
-| position | int | 顺序位置 |
+| 字段 | 类型 | 说明 |
+|-------------|--------|--------------------|
+| role_id | int | 角色 id |
+| name | string | 角色名称 |
+| color | int | 颜色色值 |
+| position | int | 顺序位置 |
| hoist | int | 是否为角色设定(与普通成员分开显示) |
-| mentionable | int | 是否允许任何人@提及此角色 |
-| permissions | int | 权限码 |
+| mentionable | int | 是否允许任何人@提及此角色 |
+| permissions | int | 权限码 |
**示例**
@@ -126,22 +126,22 @@
## 频道 Channel
-| 字段 | 类型 | 说明 |
-| --------------------- | ------- | --------------------------------------------- |
-| id | string | 频道 id |
-| name | string | 频道名称 |
-| user_id | string | 创建者 id |
-| guild_id | string | 服务器 id |
-| topic | string | 频道简介 |
-| is_category | boolean | 是否为分组，事件中为 int 格式 |
-| parent_id | string | 上级分组的 id (若没有则为 0 或空字符串) |
-| level | int | 排序 level |
+| 字段 | 类型 | 说明 |
+|-----------------------|---------|---------------------------|
+| id | string | 频道 id |
+| name | string | 频道名称 |
+| user_id | string | 创建者 id |
+| guild_id | string | 服务器 id |
+| topic | string | 频道简介 |
+| is_category | boolean | 是否为分组，事件中为 int 格式 |
+| parent_id | string | 上级分组的 id (若没有则为 0 或空字符串) |
+| level | int | 排序 level |
| slow_mode | int | 慢速模式下限制发言的最短时间间隔, 单位为秒(s) |
-| type | int | 频道类型: `1` 文字频道, `2` 语音频道 |
+| type | int | 频道类型: `1` 文字频道, `2` 语音频道 |
| permission_overwrites | Array | 针对角色在该频道的权限覆写规则组成的列表 |
| permission_users | array | 针对用户在该频道的权限覆写规则组成的列表 |
-| permission_sync | int | 权限设置是否与分组同步, `1` or `0` |
-| has_password | bool | 是否有密码 |
+| permission_sync | int | 权限设置是否与分组同步, `1` or `0` |
+| has_password | bool | 是否有密码 |
**示例**
@@ -191,13 +191,13 @@
## 引用消息 Quote
-| 字段 | 类型 | 说明 |
-| --------- | ------ | ------------------------ |
-| id | string | 引用消息 id |
-| type | int | 引用消息类型 |
-| content | string | 引用消息内容 |
+| 字段 | 类型 | 说明 |
+|-----------|--------|--------------|
+| id | string | 引用消息 id |
+| type | int | 引用消息类型 |
+| content | string | 引用消息内容 |
| create_at | int | 引用消息创建时间（毫秒） |
-| author | map | 作者的用户信息 |
+| author | map | 作者的用户信息 |
**示例**
@@ -232,10 +232,10 @@
## 附加的多媒体数据 Attachments
-| 字段 | 类型 | 说明 |
-| ---- | ------ | ------------- |
-| type | string | 多媒体类型 |
-| url | string | 多媒体地址 |
+| 字段 | 类型 | 说明 |
+|------|--------|------------|
+| type | string | 多媒体类型 |
+| url | string | 多媒体地址 |
| name | string | 多媒体名 |
| size | int | 大小 单位 Byte |
@@ -251,3 +251,78 @@
```
含有附件的消息示例详见[消息相关事件](https://developer.kookapp.cn/doc/event/message)
+
+## 热门服务器推荐信息 RecommendInfo
+
+| 字段 | 类型 | 说明 |
+|---------------------|---------|-----------------------------------------------------|
+| guild_id | string | 推荐服务器 ID |
+| open_id | string | 服务器公开 ID |
+| enable_open | int | 当为公开服务器时，此值为 `1` |
+| default_channel_id | int | 服务器默认频道 ID，若服务器的默认文字频道设置为无默认频道，则此值为服务器的首个文字频道的频道 ID |
+| name | string | 服务器名称 |
+| icon | string | 服务器图标地址 |
+| banner | string | 服务器横幅图片地址 |
+| banner_preview | string | 服务器横幅预览图片地址 |
+| desc | string | 服务器介绍 |
+| status | int | TODO |
+| guild_status | int | TODO |
+| tag | int | 服务器分类标签 |
+| features | array | 服务器特性，数组成员为 `string` 类型，其枚举值 `feature` 见表后 |
+| certifications | array | 服务器认证信息 |
+| - type | int | 服务器认证类型 |
+| - title | string | 服务器认证名称 |
+| - pic | string | 服务器认证图标地址 |
+| - desc | string | 服务器认证说明 |
+| level | integer | 服务器助力等级 |
+| custom_id | string | 服务器自定义 ID，如果服务器绑定了靓号 ID，则此字段值也可能为该靓号 ID |
+| is_official_partner | integer | 当为官方推荐服务器时，此值为 `1` |
+| sort | integer | TODO |
+| gradient | object | 推荐卡片颜色信息 |
+| audit_status | integer | TODO |
+| update_day_gap | integer | TODO |
+
+**示例**
+
+```json
+{
+ "guild_id": "3500000000000",
+ "open_id": "1600000",
+ "enable_open": 1,
+ "default_channel_id": "760000000000",
+ "name": "服务器名称",
+ "icon": "https://img.kookapp.cn/icons/2022-04/xxxxxxxx.gif",
+ "banner": "https://img.kaiheila.cn/assets/2022-06/xxxxxxxxxx.png",
+ "banner_preview": "https://img.kaiheila.cn/assets/2022-06/xxxxxxxxxxxx.png",
+ "desc": "服务器介绍",
+ "status": 1,
+ "guild_status": 0,
+ "tag": "其他社群",
+ "features": [
+ "official"
+ ],
+ "certifications": [
+ {
+ "type": 1,
+ "title": "KOOK官方服务器",
+ "pic": "https://img.kookapp.cn/assets/2023-12/xxxxxxxx.jpg",
+ "desc": ""
+ }
+ ],
+ "level": 6,
+ "custom_id": "kook",
+ "is_official_partner": 1,
+ "sort": 9999,
+ "gradient": {
+ "id": 4,
+ "color_map": [
+ "0xFFFFFF",
+ "0x000000"
+ ],
+ "limit": 5,
+ "theme": "dark"
+ },
+ "audit_status": 1,
+ "update_day_gap": 0
+}
+```