# 频道相关API

> 注意: QQ频道功能目前还在测试阶段, go-cqhttp 也在适配的初期阶段, 以下 `API` `Event` 的字段名可能存在错误并均有可能在后续版本修改/添加/删除.
> 目前仅供开发者测试以及适配使用

QQ频道相关功能的事件以及API

## 命名说明

API以及字段相关命名均为参考QQ官方命名或相似产品命名规则, 由于QQ频道的账号系统独立于QQ本体, 所以各个 `ID` 并不能和QQ通用.也无法通过 `tiny_id` 获取到 `QQ号`

下表为常见字段命名说明

| 命名         | 说明                 |
| ------------ | -------------------- |
| `tiny_id`    | 在频道系统中代表用户ID, 与QQ号并不通用 |
| `guild_id`   | 频道ID               |
| `channel_id` | 子频道ID             |

> 所有频道相关事件的 `user_id` 均为 `tiny_id`

## 特殊说明

- 由于频道的限制, 目前无法通过图片摘要查询到频道图片消息的详细信息, 所以通过频道消息收到的图片均会下载完整文件到 `images/guild-images`. (群图片转发不受此限制)
- 由于无法通过 `GlobalID` 放下频道消息的ID, 所以所有频道消息的 `message_id` 均为 `string` 类型
- `send_msg` API将无法发送频道消息
- `get_msg` API暂时无法获取频道消息
- `reply` 等消息类型暂不支持解析
- `at` 消息的 `target` 依然使用 `qq` 字段, 以保证一致性. 但内容为 `tiny_id`
- 所有事件的 `self_id` 均为 BOT 的QQ号. `tiny_id` 将放在 `self_tiny_id` 字段
- 遵循我们一贯的原则, 将不会支持主动加频道/主动拉人/红包相关消息类型
- 频道相关的API仅能在 `Android Phone` 和 `iPad` 协议上使用.
- 由于频道相关ID的数据类型均为 `uint64` , 为保证不超过某些语言的安全值范围, 在 `v1.0.0-beta8-fix3` 以后, 所有ID相关数据将转换为 `string` 类型, API调用 `uint64`
  或 `string` 均可接受.
- 为保证一致性, 所有频道接口返回的 `用户ID` 均命名为 `tiny_id`, 所有频道相关接口的 `用户ID` 入参均命名为 `user_id`

## API

### 获取频道系统内BOT的资料

终结点: `/get_guild_service_profile`

**响应数据**

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `nickname`    | string | 昵称      |
| `tiny_id`     | string | 自身的ID   |
| `avatar_url`  | string | 头像链接   |

### 获取频道列表

终结点: `/get_guild_list`

**响应数据**

正常情况下响应 `GuildInfo` 数组, 未加入任何频道响应 `null`

GuildInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `guild_id`    | string | 频道ID      |
| `guild_name`     | string | 频道名称   |
| `guild_display_id`  | int64 | 频道显示ID, 公测后可能作为搜索ID使用  |

### 通过访客获取频道元数据

终结点: `/get_guild_meta_by_guest`

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |

**响应数据**

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `guild_id`    | string | 频道ID      |
| `guild_name`     | string | 频道名称   |
| `guild_profile`  | string | 频道简介  |
| `create_time`  | int64 | 创建时间  |
| `max_member_count`  | int64 | 频道人数上限  |
| `max_robot_count`  | int64 | 频道BOT数上限  |
| `max_admin_count`  | int64 | 频道管理员人数上限  |
| `member_count`  | int64 | 已加入人数  |
| `owner_id`  | string | 创建者ID  |

### 获取子频道列表

终结点: `/get_guild_channel_list`

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |
| `no_cache` | bool  | 是否无视缓存 |

**响应数据**

正常情况下响应 `ChannelInfo` 数组, 未找到任何子频道响应 `null`

ChannelInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `owner_guild_id`    | string | 所属频道ID      |
| `channel_id`     | string | 子频道ID   |
| `channel_type`     | int32 | 子频道类型   |
| `channel_name`  | string | 子频道名称  |
| `create_time`  | int64 | 创建时间  |
| `creator_tiny_id`  | string | 创建者ID  |
| `talk_permission`  | int32 | 发言权限类型  |
| `visible_type`  | int32 | 可视性类型  |
| `current_slow_mode`  | int32 | 当前启用的慢速模式Key  |
| `slow_modes`  | []SlowModeInfo | 频道内可用慢速模式类型列表|

SlowModeInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `slow_mode_key`    | int32 | 慢速模式Key   |
| `slow_mode_text`     | string | 慢速模式说明   |
| `speak_frequency`  | int32 | 周期内发言频率限制  |
| `slow_mode_circle`  | int32 | 单位周期时间, 单位秒 |

已知子频道类型列表

| 类型          |  说明       |
| ------------- | ---------- |
| 1    | 文字频道  |
| 2     | 语音频道  |
| 5  |  直播频道  |
| 7  |  主题频道  |

### 获取频道成员列表

终结点: `/get_guild_member_list`

> 由于频道人数较多(数万), 请尽量不要全量拉取成员列表, 这将会导致严重的性能问题
>
> 尽量使用 `get_guild_member_profile` 接口代替全量拉取

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |
| `next_token` | string | 翻页Token |

> `next_token` 为空的情况下, 将返回第一页的数据, 并在返回值附带下一页的 `token`

**响应数据**

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `members`    | []GuildMemberInfo | 成员列表   |
| `finished`    | bool | 是否最终页   |
| `next_token`    | string | 翻页Token   |

GuildMemberInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `tiny_id`    | string | 成员ID   |
| `title`    | string | 成员头衔   |
| `nickname`    | string | 成员昵称   |
| `role_id`    | string | 所在权限组ID   |
| `role_name`    | string | 所在权限组名称   |

> 默认情况下频道管理员的权限组ID为 `2`, 部分频道可能会另行创建, 需手动判断
>
> 此接口仅展现最新的权限组, 获取用户加入的所有权限组请使用 `get_guild_member_profile` 接口

### 单独获取频道成员信息

终结点: `/get_guild_member_profile`

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |
| `user_id` | string | 用户ID |

**响应数据**

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `tiny_id`    | string | 用户ID     |
| `nickname`    | string | 用户昵称     |
| `avatar_url`    | string | 头像地址     |
| `join_time`    | int64 | 加入时间     |
| `roles`    | []RoleInfo | 加入的所有权限组    |

RoleInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `role_id`    | string | 权限组ID     |
| `role_name`   | string | 权限组名称     |

### 发送信息到子频道

终结点: `/send_guild_channel_msg`

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |
| `channel_id` | string | 子频道ID |
| `message` | Message | 消息, 与原有消息类型相同 |

**响应数据**

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `message_id`    | string | 消息ID     |

### 获取话题频道帖子

终结点: `/get_topic_channel_feeds`

**参数**

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `guild_id` | string | 频道ID |
| `channel_id` | string | 子频道ID |

**响应数据**

返回 `FeedInfo` 数组

FeedInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `id`   | string | 帖子ID     |
| `channel_id`    | string | 子频道ID     |
| `guild_id`   | string | 频道ID     |
| `create_time`   | int64 | 发帖时间     |
| `title`   | string | 帖子标题     |
| `sub_title`   | string | 帖子副标题  |
| `poster_info`   | PosterInfo | 发帖人信息  |
| `resource`   | ResourceInfo | 媒体资源信息  |
| `resource.images`   | []FeedMedia | 帖子附带的图片列表 |
| `resource.videos`   | []FeedMedia | 帖子附带的视频列表 |
| `contents`   | []FeedContent | 帖子内容 |

PosterInfo:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `tiny_id`   | string | 发帖人ID     |
| `nickname`    | string | 发帖人昵称     |
| `icon_url`   | string | 发帖人头像链接   |

FeedMedia:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `file_id`   | string | 媒体ID     |
| `pattern_id`    | string |   控件ID?(不确定)   |
| `url`   | string | 媒体链接   |
| `height`   | int32 | 媒体高度  |
| `width`   | int32 | 媒体宽度  |

FeedContent:

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `type`   | string |  内容类型    |
| `data`    | Data |   内容数据   |

#### 内容类型列表:

|  类型  | 说明       |
|  ----- | ---------- |
| `text` |  文本   |
| `face` |  表情   |
| `at` |  At  |
| `url_quote` |  链接引用   |
| `channel_quote` |  子频道引用  |

#### 内容类型对应数据列表:

- `text`

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `text`   | string |  文本内容    |

- `face`

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `id`   | string |  表情ID    |

- `at`

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `id`   | string |  目标ID    |
| `qq`   | string |  目标ID, 为确保和 `array message` 的一致性保留    |

- `url_quote`

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `display_text`   | string |  显示文本    |
| `url`   | string |  链接    |

- `channel_quote`

| 字段          | 类型  | 说明       |
| ------------- | ----- | ---------- |
| `display_text`   | string |  显示文本    |
| `guild_id`   | string |  频道ID    |
| `channel_id`   | string |  子频道ID    |

## 事件

### 收到频道消息

**上报数据**

| 字段          | 类型   | 可能的值       | 说明           |
| ------------- | ------ | -------------- | -------------- |
| `post_type`   | string | `message`       | 上报类型       |
| `message_type` | string | `guild` | 消息类型       |
| `sub_type` | string | `channel` | 消息子类型       |
| `guild_id`    | string  |                | 频道ID           |
| `channel_id`    | string  |                | 子频道ID           |
| `user_id`     | string  |                | 消息发送者ID   |
| `message_id`     | string  |                | 消息ID  |
| `sender`     | Sender  |                | 发送者  |
| `message`     | Message  |                | 消息内容  |

> 注: 此处的 `Sender` 对象为保证一致性, `user_id` 为 `uint64` 类型, 并添加了 `string` 类型的 `tiny_id` 字段

### 频道消息表情贴更新

**上报数据**

| 字段          | 类型   | 可能的值       | 说明           |
| ------------- | ------ | -------------- | -------------- |
| `post_type`   | string | `notice`       | 上报类型       |
| `notice_type` | string | `message_reactions_updated` | 消息类型       |
| `guild_id`    | string  |                | 频道ID           |
| `channel_id`    | string  |                | 子频道ID           |
| `user_id`     | string  |                | 操作者ID  |
| `message_id`     | string  |                | 消息ID  |
| `current_reactions`     | []ReactionInfo  |                | 当前消息被贴表情列表  |

ReactionInfo:

| 字段       | 类型  | 说明 |
| ---------- | ----- | ---- |
| `emoji_id` | string | 表情ID |
| `emoji_index` | int32 | 表情对应数值ID |
| `emoji_type` | int32 | 表情类型 |
| `emoji_name` | string | 表情名字 |
| `count` | int32 | 当前表情被贴数量 |
| `clicked` | bool | BOT是否点击 |

### 子频道信息更新

**上报数据**

| 字段          | 类型   | 可能的值       | 说明           |
| ------------- | ------ | -------------- | -------------- |
| `post_type`   | string | `notice`       | 上报类型       |
| `notice_type` | string | `channel_updated` | 消息类型       |
| `guild_id`    | string  |                | 频道ID           |
| `channel_id`    | string  |                | 子频道ID           |
| `user_id`     | string  |                | 操作者ID  |
| `operator_id`     | string  |                | 操作者ID  |
| `old_info`     | ChannelInfo  |        | 更新前的频道信息  |
| `new_info`     | ChannelInfo  |        | 更新后的频道信息  |

### 子频道创建

**上报数据**

| 字段          | 类型   | 可能的值       | 说明           |
| ------------- | ------ | -------------- | -------------- |
| `post_type`   | string | `notice`       | 上报类型       |
| `notice_type` | string | `channel_created` | 消息类型       |
| `guild_id`    | string  |                | 频道ID           |
| `channel_id`    | string  |                | 子频道ID           |
| `user_id`     | string  |                | 操作者ID  |
| `operator_id`     | string  |                | 操作者ID  |
| `channel_info`     | ChannelInfo  |        | 频道信息  |

### 子频道删除

**上报数据**

| 字段          | 类型   | 可能的值       | 说明           |
| ------------- | ------ | -------------- | -------------- |
| `post_type`   | string | `notice`       | 上报类型       |
| `notice_type` | string | `channel_destroyed` | 消息类型       |
| `guild_id`    | string  |                | 频道ID           |
| `channel_id`    | string  |                | 子频道ID           |
| `user_id`     | string  |                | 操作者ID  |
| `operator_id`     | string  |                | 操作者ID  |
| `channel_info`     | ChannelInfo  |        | 频道信息  |