github.com/Mrs4s/go-cqhttp@v1.2.0/docs/guild.md (about) 1 # 频道相关API 2 3 > 注意: QQ频道功能目前还在测试阶段, go-cqhttp 也在适配的初期阶段, 以下 `API` `Event` 的字段名可能存在错误并均有可能在后续版本修改/添加/删除. 4 > 目前仅供开发者测试以及适配使用 5 6 QQ频道相关功能的事件以及API 7 8 > 注意, 最新文档已经移动到 [go-cqhttp-docs](https://github.com/ishkong/go-cqhttp-docs), 当前文档只做兼容性保留, 所以内容可能有不足. 9 10 ## 命名说明 11 12 API以及字段相关命名均为参考QQ官方命名或相似产品命名规则, 由于QQ频道的账号系统独立于QQ本体, 所以各个 `ID` 并不能和QQ通用.也无法通过 `tiny_id` 获取到 `QQ号` 13 14 下表为常见字段命名说明 15 16 | 命名 | 说明 | 17 | ------------ | -------------------- | 18 | `tiny_id` | 在频道系统中代表用户ID, 与QQ号并不通用 | 19 | `guild_id` | 频道ID | 20 | `channel_id` | 子频道ID | 21 22 > 所有频道相关事件的 `user_id` 均为 `tiny_id` 23 24 ## 特殊说明 25 26 - 由于频道的限制, 目前无法通过图片摘要查询到频道图片消息的详细信息, 所以通过频道消息收到的图片均会下载完整文件到 `images/guild-images`. (群图片转发不受此限制) 27 - 由于无法通过 `GlobalID` 放下频道消息的ID, 所以所有频道消息的 `message_id` 均为 `string` 类型 28 - `send_msg` API将无法发送频道消息 29 - `get_msg` API暂时无法获取频道消息 30 - `reply` 等消息类型暂不支持解析 31 - `at` 消息的 `target` 依然使用 `qq` 字段, 以保证一致性. 但内容为 `tiny_id` 32 - 所有事件的 `self_id` 均为 BOT 的QQ号. `tiny_id` 将放在 `self_tiny_id` 字段 33 - 遵循我们一贯的原则, 将不会支持主动加频道/主动拉人/红包相关消息类型 34 - 频道相关的API仅能在 `Android Phone` 和 `iPad` 协议上使用. 35 - 由于频道相关ID的数据类型均为 `uint64` , 为保证不超过某些语言的安全值范围, 在 `v1.0.0-beta8-fix3` 以后, 所有ID相关数据将转换为 `string` 类型, API调用 `uint64` 36 或 `string` 均可接受. 37 - 为保证一致性, 所有频道接口返回的 `用户ID` 均命名为 `tiny_id`, 所有频道相关接口的 `用户ID` 入参均命名为 `user_id` 38 39 ## API 40 41 ### 获取频道系统内BOT的资料 42 43 终结点: `/get_guild_service_profile` 44 45 **响应数据** 46 47 | 字段 | 类型 | 说明 | 48 | ------------- | ----- | ---------- | 49 | `nickname` | string | 昵称 | 50 | `tiny_id` | string | 自身的ID | 51 | `avatar_url` | string | 头像链接 | 52 53 ### 获取频道列表 54 55 终结点: `/get_guild_list` 56 57 **响应数据** 58 59 正常情况下响应 `GuildInfo` 数组, 未加入任何频道响应 `null` 60 61 GuildInfo: 62 63 | 字段 | 类型 | 说明 | 64 | ------------- | ----- | ---------- | 65 | `guild_id` | string | 频道ID | 66 | `guild_name` | string | 频道名称 | 67 | `guild_display_id` | int64 | 频道显示ID, 公测后可能作为搜索ID使用 | 68 69 ### 通过访客获取频道元数据 70 71 终结点: `/get_guild_meta_by_guest` 72 73 **参数** 74 75 | 字段 | 类型 | 说明 | 76 | ---------- | ----- | ---- | 77 | `guild_id` | string | 频道ID | 78 79 **响应数据** 80 81 | 字段 | 类型 | 说明 | 82 | ------------- | ----- | ---------- | 83 | `guild_id` | string | 频道ID | 84 | `guild_name` | string | 频道名称 | 85 | `guild_profile` | string | 频道简介 | 86 | `create_time` | int64 | 创建时间 | 87 | `max_member_count` | int64 | 频道人数上限 | 88 | `max_robot_count` | int64 | 频道BOT数上限 | 89 | `max_admin_count` | int64 | 频道管理员人数上限 | 90 | `member_count` | int64 | 已加入人数 | 91 | `owner_id` | string | 创建者ID | 92 93 ### 获取子频道列表 94 95 终结点: `/get_guild_channel_list` 96 97 **参数** 98 99 | 字段 | 类型 | 说明 | 100 | ---------- | ----- | ---- | 101 | `guild_id` | string | 频道ID | 102 | `no_cache` | bool | 是否无视缓存 | 103 104 **响应数据** 105 106 正常情况下响应 `ChannelInfo` 数组, 未找到任何子频道响应 `null` 107 108 ChannelInfo: 109 110 | 字段 | 类型 | 说明 | 111 | ------------- | ----- | ---------- | 112 | `owner_guild_id` | string | 所属频道ID | 113 | `channel_id` | string | 子频道ID | 114 | `channel_type` | int32 | 子频道类型 | 115 | `channel_name` | string | 子频道名称 | 116 | `create_time` | int64 | 创建时间 | 117 | `creator_tiny_id` | string | 创建者ID | 118 | `talk_permission` | int32 | 发言权限类型 | 119 | `visible_type` | int32 | 可视性类型 | 120 | `current_slow_mode` | int32 | 当前启用的慢速模式Key | 121 | `slow_modes` | []SlowModeInfo | 频道内可用慢速模式类型列表| 122 123 SlowModeInfo: 124 125 | 字段 | 类型 | 说明 | 126 | ------------- | ----- | ---------- | 127 | `slow_mode_key` | int32 | 慢速模式Key | 128 | `slow_mode_text` | string | 慢速模式说明 | 129 | `speak_frequency` | int32 | 周期内发言频率限制 | 130 | `slow_mode_circle` | int32 | 单位周期时间, 单位秒 | 131 132 已知子频道类型列表 133 134 | 类型 | 说明 | 135 | ------------- | ---------- | 136 | 1 | 文字频道 | 137 | 2 | 语音频道 | 138 | 5 | 直播频道 | 139 | 7 | 主题频道 | 140 141 ### 获取频道成员列表 142 143 终结点: `/get_guild_member_list` 144 145 > 由于频道人数较多(数万), 请尽量不要全量拉取成员列表, 这将会导致严重的性能问题 146 > 147 > 尽量使用 `get_guild_member_profile` 接口代替全量拉取 148 149 **参数** 150 151 | 字段 | 类型 | 说明 | 152 | ---------- | ----- | ---- | 153 | `guild_id` | string | 频道ID | 154 | `next_token` | string | 翻页Token | 155 156 > `next_token` 为空的情况下, 将返回第一页的数据, 并在返回值附带下一页的 `token` 157 158 **响应数据** 159 160 | 字段 | 类型 | 说明 | 161 | ------------- | ----- | ---------- | 162 | `members` | []GuildMemberInfo | 成员列表 | 163 | `finished` | bool | 是否最终页 | 164 | `next_token` | string | 翻页Token | 165 166 GuildMemberInfo: 167 168 | 字段 | 类型 | 说明 | 169 | ------------- | ----- | ---------- | 170 | `tiny_id` | string | 成员ID | 171 | `title` | string | 成员头衔 | 172 | `nickname` | string | 成员昵称 | 173 | `role_id` | string | 所在权限组ID | 174 | `role_name` | string | 所在权限组名称 | 175 176 > 默认情况下频道管理员的权限组ID为 `2`, 部分频道可能会另行创建, 需手动判断 177 > 178 > 此接口仅展现最新的权限组, 获取用户加入的所有权限组请使用 `get_guild_member_profile` 接口 179 180 ### 单独获取频道成员信息 181 182 终结点: `/get_guild_member_profile` 183 184 **参数** 185 186 | 字段 | 类型 | 说明 | 187 | ---------- | ----- | ---- | 188 | `guild_id` | string | 频道ID | 189 | `user_id` | string | 用户ID | 190 191 **响应数据** 192 193 | 字段 | 类型 | 说明 | 194 | ------------- | ----- | ---------- | 195 | `tiny_id` | string | 用户ID | 196 | `nickname` | string | 用户昵称 | 197 | `avatar_url` | string | 头像地址 | 198 | `join_time` | int64 | 加入时间 | 199 | `roles` | []RoleInfo | 加入的所有权限组 | 200 201 RoleInfo: 202 203 | 字段 | 类型 | 说明 | 204 | ------------- | ----- | ---------- | 205 | `role_id` | string | 权限组ID | 206 | `role_name` | string | 权限组名称 | 207 208 ### 发送信息到子频道 209 210 终结点: `/send_guild_channel_msg` 211 212 **参数** 213 214 | 字段 | 类型 | 说明 | 215 | ---------- | ----- | ---- | 216 | `guild_id` | string | 频道ID | 217 | `channel_id` | string | 子频道ID | 218 | `message` | Message | 消息, 与原有消息类型相同 | 219 220 **响应数据** 221 222 | 字段 | 类型 | 说明 | 223 | ------------- | ----- | ---------- | 224 | `message_id` | string | 消息ID | 225 226 ### 获取话题频道帖子 227 228 终结点: `/get_topic_channel_feeds` 229 230 **参数** 231 232 | 字段 | 类型 | 说明 | 233 | ---------- | ----- | ---- | 234 | `guild_id` | string | 频道ID | 235 | `channel_id` | string | 子频道ID | 236 237 **响应数据** 238 239 返回 `FeedInfo` 数组 240 241 FeedInfo: 242 243 | 字段 | 类型 | 说明 | 244 | ------------- | ----- | ---------- | 245 | `id` | string | 帖子ID | 246 | `channel_id` | string | 子频道ID | 247 | `guild_id` | string | 频道ID | 248 | `create_time` | int64 | 发帖时间 | 249 | `title` | string | 帖子标题 | 250 | `sub_title` | string | 帖子副标题 | 251 | `poster_info` | PosterInfo | 发帖人信息 | 252 | `resource` | ResourceInfo | 媒体资源信息 | 253 | `resource.images` | []FeedMedia | 帖子附带的图片列表 | 254 | `resource.videos` | []FeedMedia | 帖子附带的视频列表 | 255 | `contents` | []FeedContent | 帖子内容 | 256 257 PosterInfo: 258 259 | 字段 | 类型 | 说明 | 260 | ------------- | ----- | ---------- | 261 | `tiny_id` | string | 发帖人ID | 262 | `nickname` | string | 发帖人昵称 | 263 | `icon_url` | string | 发帖人头像链接 | 264 265 FeedMedia: 266 267 | 字段 | 类型 | 说明 | 268 | ------------- | ----- | ---------- | 269 | `file_id` | string | 媒体ID | 270 | `pattern_id` | string | 控件ID?(不确定) | 271 | `url` | string | 媒体链接 | 272 | `height` | int32 | 媒体高度 | 273 | `width` | int32 | 媒体宽度 | 274 275 FeedContent: 276 277 | 字段 | 类型 | 说明 | 278 | ------------- | ----- | ---------- | 279 | `type` | string | 内容类型 | 280 | `data` | Data | 内容数据 | 281 282 #### 内容类型列表: 283 284 | 类型 | 说明 | 285 | ----- | ---------- | 286 | `text` | 文本 | 287 | `face` | 表情 | 288 | `at` | At | 289 | `url_quote` | 链接引用 | 290 | `channel_quote` | 子频道引用 | 291 292 #### 内容类型对应数据列表: 293 294 - `text` 295 296 | 字段 | 类型 | 说明 | 297 | ------------- | ----- | ---------- | 298 | `text` | string | 文本内容 | 299 300 - `face` 301 302 | 字段 | 类型 | 说明 | 303 | ------------- | ----- | ---------- | 304 | `id` | string | 表情ID | 305 306 - `at` 307 308 | 字段 | 类型 | 说明 | 309 | ------------- | ----- | ---------- | 310 | `id` | string | 目标ID | 311 | `qq` | string | 目标ID, 为确保和 `array message` 的一致性保留 | 312 313 - `url_quote` 314 315 | 字段 | 类型 | 说明 | 316 | ------------- | ----- | ---------- | 317 | `display_text` | string | 显示文本 | 318 | `url` | string | 链接 | 319 320 - `channel_quote` 321 322 | 字段 | 类型 | 说明 | 323 | ------------- | ----- | ---------- | 324 | `display_text` | string | 显示文本 | 325 | `guild_id` | string | 频道ID | 326 | `channel_id` | string | 子频道ID | 327 328 ## 事件 329 330 ### 收到频道消息 331 332 **上报数据** 333 334 | 字段 | 类型 | 可能的值 | 说明 | 335 | ------------- | ------ | -------------- | -------------- | 336 | `post_type` | string | `message` | 上报类型 | 337 | `message_type` | string | `guild` | 消息类型 | 338 | `sub_type` | string | `channel` | 消息子类型 | 339 | `guild_id` | string | | 频道ID | 340 | `channel_id` | string | | 子频道ID | 341 | `user_id` | string | | 消息发送者ID | 342 | `message_id` | string | | 消息ID | 343 | `sender` | Sender | | 发送者 | 344 | `message` | Message | | 消息内容 | 345 346 > 注: 此处的 `Sender` 对象为保证一致性, `user_id` 为 `uint64` 类型, 并添加了 `string` 类型的 `tiny_id` 字段 347 348 ### 频道消息表情贴更新 349 350 **上报数据** 351 352 | 字段 | 类型 | 可能的值 | 说明 | 353 | ------------- | ------ | -------------- | -------------- | 354 | `post_type` | string | `notice` | 上报类型 | 355 | `notice_type` | string | `message_reactions_updated` | 消息类型 | 356 | `guild_id` | string | | 频道ID | 357 | `channel_id` | string | | 子频道ID | 358 | `user_id` | string | | 操作者ID | 359 | `message_id` | string | | 消息ID | 360 | `current_reactions` | []ReactionInfo | | 当前消息被贴表情列表 | 361 362 ReactionInfo: 363 364 | 字段 | 类型 | 说明 | 365 | ---------- | ----- | ---- | 366 | `emoji_id` | string | 表情ID | 367 | `emoji_index` | int32 | 表情对应数值ID | 368 | `emoji_type` | int32 | 表情类型 | 369 | `emoji_name` | string | 表情名字 | 370 | `count` | int32 | 当前表情被贴数量 | 371 | `clicked` | bool | BOT是否点击 | 372 373 ### 子频道信息更新 374 375 **上报数据** 376 377 | 字段 | 类型 | 可能的值 | 说明 | 378 | ------------- | ------ | -------------- | -------------- | 379 | `post_type` | string | `notice` | 上报类型 | 380 | `notice_type` | string | `channel_updated` | 消息类型 | 381 | `guild_id` | string | | 频道ID | 382 | `channel_id` | string | | 子频道ID | 383 | `user_id` | string | | 操作者ID | 384 | `operator_id` | string | | 操作者ID | 385 | `old_info` | ChannelInfo | | 更新前的频道信息 | 386 | `new_info` | ChannelInfo | | 更新后的频道信息 | 387 388 ### 子频道创建 389 390 **上报数据** 391 392 | 字段 | 类型 | 可能的值 | 说明 | 393 | ------------- | ------ | -------------- | -------------- | 394 | `post_type` | string | `notice` | 上报类型 | 395 | `notice_type` | string | `channel_created` | 消息类型 | 396 | `guild_id` | string | | 频道ID | 397 | `channel_id` | string | | 子频道ID | 398 | `user_id` | string | | 操作者ID | 399 | `operator_id` | string | | 操作者ID | 400 | `channel_info` | ChannelInfo | | 频道信息 | 401 402 ### 子频道删除 403 404 **上报数据** 405 406 | 字段 | 类型 | 可能的值 | 说明 | 407 | ------------- | ------ | -------------- | -------------- | 408 | `post_type` | string | `notice` | 上报类型 | 409 | `notice_type` | string | `channel_destroyed` | 消息类型 | 410 | `guild_id` | string | | 频道ID | 411 | `channel_id` | string | | 子频道ID | 412 | `user_id` | string | | 操作者ID | 413 | `operator_id` | string | | 操作者ID | 414 | `channel_info` | ChannelInfo | | 频道信息 |