shkong/go-cqhttp
1
0
Fork 0
mirror of https://github.com/Mrs4s/go-cqhttp.git synced 2025-05-04 19:17:37 +08:00
Code Issues Projects Releases Wiki Activity
go-cqhttp/docs/guild.md
SlimeNull 43004e2496 全部添加 "文档已移动" 提示
2023-01-13 18:32:55 +08:00

414 lines
14 KiB
Markdown
Raw Permalink Blame History

# 频道相关API
> 注意: QQ频道功能目前还在测试阶段, go-cqhttp 也在适配的初期阶段, 以下 `API` `Event` 的字段名可能存在错误并均有可能在后续版本修改/添加/删除.
> 目前仅供开发者测试以及适配使用
QQ频道相关功能的事件以及API
> 注意, 最新文档已经移动到 [go-cqhttp-docs](https://github.com/ishkong/go-cqhttp-docs), 当前文档只做兼容性保留, 所以内容可能有不足.
## 命名说明
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 | | 频道信息 |
Reference in New Issue View Git Blame Copy Permalink