github.com/Mrs4s/go-cqhttp@v1.2.0/docs/cqhttp.md (about) 1 # 拓展API 2 3 由于部分 api 原版 CQHTTP 并未实现，go-cqhttp 修改并增加了一些拓展 api 4 5 > 注意, 最新文档已经移动到 [go-cqhttp-docs](https://github.com/ishkong/go-cqhttp-docs), 当前文档只做兼容性保留, 所以内容可能有不足.. 6 7 <details> 8 <summary>目录</summary> 9 <p> 10 11 ##### CQCode 12 13 - [图片](#图片) 14 - [回复](#回复) 15 - [红包](#红包) 16 - [戳一戳](#戳一戳) 17 - [合并转发](#合并转发) 18 - [合并转发消息节点](#合并转发消息节点) 19 - [XML 消息](#xml-消息) 20 - [JSON 消息](#json-消息) 21 - [cardimage](#cardimage) 22 - [文本转语音](#文本转语音) 23 - [图片](#图片) 24 25 ##### API 26 27 - [设置群名](#设置群名) 28 - [设置群头像](#设置群头像) 29 - [获取图片信息](#获取图片信息) 30 - [获取消息](#获取消息) 31 - [获取合并转发内容](#获取合并转发内容) 32 - [发送合并转发(群)](#发送合并转发群) 33 - [获取中文分词](#获取中文分词) 34 - [图片OCR](#图片ocr) 35 - [获取群系统消息](#获取群文件系统信息) 36 - [获取群文件系统信息](#获取群文件系统信息) 37 - [获取群根目录文件列表](#获取群根目录文件列表) 38 - [获取群子目录文件列表](#获取群子目录文件列表) 39 - [获取群文件资源链接](#获取群文件资源链接) 40 - [获取状态](#获取状态) 41 - [获取群@全体成员剩余次数](#获取群全体成员剩余次数) 42 - [下载文件到缓存目录](#下载文件到缓存目录) 43 - [获取群消息历史记录](#获取群消息历史记录) 44 - [设置群名](#设置群名) 45 - [获取用户VIP信息](#获取用户vip信息) 46 - [发送群公告](#发送群公告) 47 - [获取群公告](#获取群公告) 48 - [删除群公告](#删除群公告) 49 - [设置精华消息](#设置精华消息) 50 - [移出精华消息](#移出精华消息) 51 - [获取精华消息列表](#获取精华消息列表) 52 - [重载事件过滤器](#重载事件过滤器) 53 54 ##### 事件 55 56 - [群消息撤回](#群消息撤回) 57 - [好友消息撤回](#好友消息撤回) 58 - [好友戳一戳](#好友戳一戳) 59 - [群内戳一戳](#群内戳一戳) 60 - [群红包运气王提示](#群红包运气王提示) 61 - [群成员荣誉变更提示](#群成员荣誉变更提示) 62 - [群成员名片更新](#群成员名片更新) 63 - [接收到离线文件](#接收到离线文件) 64 - [群精华消息](#精华消息) 65 66 </p> 67 </details> 68 69 ## CQCode 70 71 ### 图片 72 73 Type : `image` 74 75 范围: **发送/接收** 76 77 参数: 78 79 | 参数名 | 可能的值 | 说明 | 80 | ------- | --------------- | ---------------------------------------------------------------------- | 81 | `file` | - | 图片文件名 | 82 | `type` | `flash`，`show` | 图片类型，`flash` 表示闪照，`show` 表示秀图，默认普通图片 | 83 | `subType`| - | 图片子类型, 只出现在群聊. | 84 | `url` | - | 图片 URL | 85 | `cache` | `0` `1` | 只在通过网络 URL 发送时有效，表示是否使用已缓存的文件，默认 `1` | 86 | `id` | - | 发送秀图时的特效id，默认为40000 | 87 | `c` | `2` `3` | 通过网络下载图片时的线程数, 默认单线程. (在资源不支持并发时会自动处理) | 88 89 可用的特效ID: 90 91 | id | 类型 | 92 | ----- | ---- | 93 | 40000 | 普通 | 94 | 40001 | 幻影 | 95 | 40002 | 抖动 | 96 | 40003 | 生日 | 97 | 40004 | 爱你 | 98 | 40005 | 征友 | 99 100 子类型列表: 101 102 | value | 说明 | 103 | ----- | ---- | 104 | 0 | 正常图片 | 105 | 1 | 表情包, 在客户端会被分类到表情包图片并缩放显示 | 106 | 2 | 热图 | 107 | 3 | 斗图 | 108 | 4 | 智图? | 109 | 7 | 贴图 | 110 | 8 | 自拍 | 111 | 9 | 贴图广告? | 112 | 10 | 有待测试 | 113 | 13 | 热搜图 | 114 115 示例: `[CQ:image,file=http://baidu.com/1.jpg,type=show,id=40004]` 116 117 > 注意：图片总大小不能超过30MB，gif总帧数不能超过300帧 118 119 ### 回复 120 121 Type : `reply` 122 123 范围: **发送/接收** 124 125 > 注意: 如果id存在则优先处理id 126 127 参数: 128 129 | 参数名 | 类型 | 说明 | 130 | ------ | ------ | --------------------------------------------------- | 131 | `id` | int | 回复时所引用的消息id, 必须为本群消息. | 132 | `text` | string | 自定义回复的信息 | 133 | `qq` | int64 | 自定义回复时的自定义QQ, 如果使用自定义信息必须指定. | 134 | `time` | int64 | 可选. 自定义回复时的时间, 格式为Unix时间 | 135 | `seq` | int64 | 起始消息序号, 可通过 `get_msg` 获得 | 136 137 示例: `[CQ:reply,id=123456]` 138 \ 139 自定义回复示例: `[CQ:reply,text=Hello World,qq=10086,time=3376656000,seq=5123]` 140 141 ### 音乐分享 <Badge text="发"/> 142 143 ```json 144 { 145 "type": "music", 146 "data": { 147 "type": "163", 148 "id": "28949129" 149 } 150 } 151 ``` 152 153 ``` 154 [CQ:music,type=163,id=28949129] 155 ``` 156 157 | 参数名 | 收 | 发 | 可能的值 | 说明 | 158 | ------ | --- | --- | ---------- | -------------------------------- | 159 | `type` | | ✓ | `qq` `163` | 分别表示使用 QQ 音乐、网易云音乐 | 160 | `id` | | ✓ | - | 歌曲 ID | 161 162 ### 音乐自定义分享 <Badge text="发"/> 163 164 ```json 165 { 166 "type": "music", 167 "data": { 168 "type": "custom", 169 "url": "http://baidu.com", 170 "audio": "http://baidu.com/1.mp3", 171 "title": "音乐标题" 172 } 173 } 174 ``` 175 176 ``` 177 [CQ:music,type=custom,url=http://baidu.com,audio=http://baidu.com/1.mp3,title=音乐标题] 178 ``` 179 180 | 参数名 | 收 | 发 | 可能的值 | 说明 | 181 | --------- | --- | --- | ------------------------ | ----------------------------------------------------- | 182 | `type` | | ✓ | `custom` | 表示音乐自定义分享 | 183 | `subtype` | | ✓ | `qq,163,migu,kugou,kuwo` | 表示分享类型，不填写发送为xml卡片，推荐填写提高稳定性 | 184 | `url` | | ✓ | - | 点击后跳转目标 URL | 185 | `audio` | | ✓ | - | 音乐 URL | 186 | `title` | | ✓ | - | 标题 | 187 | `content` | | ✓ | - | 内容描述 | 188 | `image` | | ✓ | - | 图片 URL | 189 190 ### 红包 191 192 Type: `redbag` 193 194 范围: **接收** 195 196 参数: 197 198 | 参数名 | 类型 | 说明 | 199 | ------- | ------ | ----------- | 200 | `title` | string | 祝福语/口令 | 201 202 示例: `[CQ:redbag,title=恭喜发财]` 203 204 ### 戳一戳 205 206 > 注意：发送戳一戳消息无法撤回，返回的 `message id` 恒定为 `0` 207 208 Type: `poke` 209 210 范围: **发送(仅群聊)** 211 212 参数: 213 214 | 参数名 | 类型 | 说明 | 215 | ------ | ----- | ------------ | 216 | `qq` | int64 | 需要戳的成员 | 217 218 示例: `[CQ:poke,qq=123456]` 219 220 ### 合并转发 221 222 Type: `forward` 223 224 范围: **接收** 225 226 参数: 227 228 | 参数名 | 类型 | 说明 | 229 | ------ | ------ | ------------------------------------------------------------- | 230 | `id` | string | 合并转发ID, 需要通过 `/get_forward_msg` API获取转发的具体内容 | 231 232 示例: `[CQ:forward,id=xxxx]` 233 234 ### 合并转发消息节点 235 236 Type: `node` 237 238 范围: **发送** 239 240 参数: 241 242 | 参数名 | 类型 | 说明 | 特殊说明 | 243 | --------- | ------- | -------------- | -------------------------------------------------------------------------------------- | 244 | `id` | int32 | 转发消息id | 直接引用他人的消息合并转发, 实际查看顺序为原消息发送顺序 **与下面的自定义消息二选一** | 245 | `name` | string | 发送者显示名字 | 用于自定义消息 (自定义消息并合并转发，实际查看顺序为自定义消息段顺序) | 246 | `uin` | int64 | 发送者QQ号 | 用于自定义消息 | 247 | `content` | message | 具体消息 | 用于自定义消息 | 248 | `seq` | message | 具体消息 | 用于自定义消息 | 249 250 特殊说明: **需要使用单独的API `/send_group_forward_msg` 发送，并且由于消息段较为复杂，仅支持Array形式入参。 如果引用消息和自定义消息同时出现，实际查看顺序将取消息段顺序. 251 另外按 [Onebot v11](https://github.com/botuniverse/onebot-11/blob/master/message/array.md) 文档说明, `data` 应全为字符串, 252 但由于需要接收`message` 类型的消息, 所以 *仅限此Type的content字段* 支持Array套娃** 253 254 示例: 255 256 直接引用消息合并转发: 257 258 ````json 259 [ 260 { 261 "type": "node", 262 "data": { 263 "id": "123" 264 } 265 }, 266 { 267 "type": "node", 268 "data": { 269 "id": "456" 270 } 271 } 272 ] 273 ```` 274 275 自定义消息合并转发: 276 277 ````json 278 [ 279 { 280 "type": "node", 281 "data": { 282 "name": "消息发送者A", 283 "uin": "10086", 284 "content": [ 285 { 286 "type": "text", 287 "data": { 288 "text": "测试消息1" 289 } 290 } 291 ] 292 } 293 }, 294 { 295 "type": "node", 296 "data": { 297 "name": "消息发送者B", 298 "uin": "10087", 299 "content": "[CQ:image,file=xxxxx]测试消息2" 300 } 301 } 302 ] 303 ```` 304 305 引用自定义混合合并转发: 306 307 ````json 308 [ 309 { 310 "type": "node", 311 "data": { 312 "name": "自定义发送者", 313 "uin": "10086", 314 "content": "我是自定义消息", 315 "seq": "5123", 316 "time": "3376656000" 317 } 318 }, 319 { 320 "type": "node", 321 "data": { 322 "id": "123" 323 } 324 } 325 ] 326 ```` 327 328 ### 短视频消息 329 330 Type: `video` 331 332 范围: **发送/接收** 333 334 参数: 335 336 | 参数名 | 类型 | 说明 | 337 | ------- | ------- | ---------------------------------------------------------------------- | 338 | `file` | string | 支持http和file发送 | 339 | `cover` | string | 视频封面，支持http，file和base64发送，格式必须为jpg | 340 | `c` | `2` `3` | 通过网络下载视频时的线程数, 默认单线程. (在资源不支持并发时会自动处理) | 341 342 示例: `[CQ:video,file=file:///C:\\Users\Richard\Videos\1.mp4]` 343 344 ### XML 消息 345 346 Type: `xml` 347 348 范围: **发送/接收** 349 350 参数: 351 352 | 参数名 | 类型 | 说明 | 353 | ------- | ------ | ----------------------------------------- | 354 | `data` | string | xml内容，xml中的value部分，记得实体化处理 | 355 | `resid` | int32 | 可以不填 | 356 357 示例: `[CQ:xml,data=xxxx]` 358 359 #### 一些xml样例 360 361 #### ps:重要：xml中的value部分，记得html实体化处理后，再打加入到cq码中 362 363 #### qq音乐 364 365 ```xml 366 <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> 367 <msg serviceID="2" templateID="1" action="web" brief="[分享] 十年" sourceMsgId="0" 368 url="https://i.y.qq.com/v8/playsong.html?_wv=1&songid=4830342&souce=qqshare&source=qqshare&ADTAG=qqshare" 369 flag="0" adverSign="0" multiMsgFlag="0"> 370 <item layout="2"> 371 <audio cover="http://imgcache.qq.com/music/photo/album_500/26/500_albumpic_89526_0.jpg" 372 src="http://ws.stream.qqmusic.qq.com/C400003mAan70zUy5O.m4a?guid=1535153710&vkey=D5315B8C0603653592AD4879A8A3742177F59D582A7A86546E24DD7F282C3ACF81526C76E293E57EA1E42CF19881C561275D919233333ADE&uin=&fromtag=3"/> 373 <title>十年</title> 374 <summary>陈奕迅</summary> 375 </item> 376 <source name="QQ音乐" icon="https://i.gtimg.cn/open/app_icon/01/07/98/56/1101079856_100_m.png" 377 url="http://web.p.qq.com/qqmpmobile/aio/app.html?id=1101079856" action="app" 378 a_actionData="com.tencent.qqmusic" i_actionData="tencent1101079856://" appid="1101079856"/> 379 </msg> 380 ``` 381 382 #### 网易音乐 383 384 ```xml 385 <?xml version='1.0' encoding='UTF-8' standalone='yes' ?> 386 <msg serviceID="2" templateID="1" action="web" brief="[分享] 十年" sourceMsgId="0" 387 url="http://music.163.com/m/song/409650368" flag="0" adverSign="0" multiMsgFlag="0"> 388 <item layout="2"> 389 <audio cover="http://p2.music.126.net/g-Qgb9ibk9Wp_0HWra0xQQ==/16636710440565853.jpg?param=90y90" 390 src="https://music.163.com/song/media/outer/url?id=409650368.mp3"/> 391 <title>十年</title> 392 <summary>黄梦之</summary> 393 </item> 394 <source name="网易云音乐" icon="https://pic.rmb.bdstatic.com/911423bee2bef937975b29b265d737b3.png" 395 url="http://web.p.qq.com/qqmpmobile/aio/app.html?id=1101079856" action="app" 396 a_actionData="com.netease.cloudmusic" i_actionData="tencent100495085://" appid="100495085"/> 397 </msg> 398 ``` 399 400 #### 卡片消息1 401 402 ```xml 403 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> 404 <msg serviceID="1"> 405 <item> 406 <title>生死8秒！女司机高速急刹，他一个操作救下一车性命</title> 407 </item> 408 <source name="官方认证消息" icon="https://qzs.qq.com/ac/qzone_v5/client/auth_icon.png" action="" appid="-1"/> 409 </msg> 410 ``` 411 412 #### 卡片消息2 413 414 ```xml 415 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> 416 <msg serviceID="1"> 417 <item layout="4"> 418 <title>test title</title> 419 <picture cover="http://url.cn/5CEwIUy"/> 420 </item> 421 </msg> 422 ``` 423 424 ### JSON 消息 425 426 Type: `json` 427 428 范围: **发送/接收** 429 430 参数: 431 432 | 参数名 | 类型 | 说明 | 433 | ------- | ------ | ----------------------------------------------- | 434 | `data` | string | json内容，json的所有字符串记得实体化处理 | 435 | `resid` | int32 | 默认不填为0，走小程序通道，填了走富文本通道发送 | 436 437 json中的字符串需要进行转义： 438 439 > ","=> `,` 440 441 > "&"=> `&` 442 443 > "["=> `[` 444 445 > "]"=> `]` 446 447 否则无法正确得到解析 448 449 示例json 的cq码： 450 451 ```test 452 [CQ:json,data={"app":"com.tencent.miniapp","desc":"","view":"notification","ver":"0.0.0.1","prompt":"[应用]","appID":"","sourceName":"","actionData":"","actionData_A":"","sourceUrl":"","meta":{"notification":{"appInfo":{"appName":"全国疫情数据统计","appType":4,"appid":1109659848,"iconUrl":"http:\/\/gchat.qpic.cn\/gchatpic_new\/719328335\/-2010394141-6383A777BEB79B70B31CE250142D740F\/0"},"data":[{"title":"确诊","value":"80932"},{"title":"今日确诊","value":"28"},{"title":"疑似","value":"72"},{"title":"今日疑似","value":"5"},{"title":"治愈","value":"60197"},{"title":"今日治愈","value":"1513"},{"title":"死亡","value":"3140"},{"title":"今**亡","value":"17"}],"title":"中国加油，武汉加油","button":[{"name":"病毒：SARS-CoV-2，其导致疾病命名 COVID-19","action":""},{"name":"传染源：新冠肺炎的患者。无症状感染者也可能成为传染源。","action":""}],"emphasis_keyword":""}},"text":"","sourceAd":""}] 453 ``` 454 455 ### cardimage 456 457 一种xml的图片消息（装逼大图） 458 459 ps: xml 接口的消息都存在风控风险，请自行兼容发送失败后的处理（可以失败后走普通图片模式） 460 461 Type: `cardimage` 462 463 范围: **发送** 464 465 参数: 466 467 | 参数名 | 类型 | 说明 | 468 | ----------- | ------ | ------------------------------------- | 469 | `file` | string | 和image的file字段对齐，支持也是一样的 | 470 | `minwidth` | int64 | 默认不填为400，最小width | 471 | `minheight` | int64 | 默认不填为400，最小height | 472 | `maxwidth` | int64 | 默认不填为500，最大width | 473 | `maxheight` | int64 | 默认不填为1000，最大height | 474 | `source` | string | 分享来源的名称，可以留空 | 475 | `icon` | string | 分享来源的icon图标url，可以留空 | 476 477 示例cardimage 的cq码： 478 479 ```test 480 [CQ:cardimage,file=https://i.pixiv.cat/img-master/img/2020/03/25/00/00/08/80334602_p0_master1200.jpg] 481 ``` 482 483 ### 文本转语音 484 485 > 注意：通过TX的TTS接口，采用的音源与登录账号的性别有关 486 487 Type: `tts` 488 489 范围: **发送(仅群聊)** 490 491 参数: 492 493 | 参数名 | 类型 | 说明 | 494 | ------ | ------ | ---- | 495 | `text` | string | 内容 | 496 497 示例: `[CQ:tts,text=这是一条测试消息]` 498 499 ### 猜拳消息 500 501 Type: `rps` 502 503 参数: 504 505 | 参数名 | 类型 | 说明 | 506 |---------|-----|------------------| 507 | `value` | int | 0：石头, 1：剪刀, 2：布 | 508 509 示例: `[CQ:rps,value=0]` 510 511 ## API 512 513 ### 设置群名 514 515 终结点: `/set_group_name` 516 517 **参数** 518 519 | 字段 | 类型 | 说明 | 520 | ------------ | ------ | ---- | 521 | `group_id` | int64 | 群号 | 522 | `group_name` | string | 新名 | 523 524 ### 设置群头像 525 526 终结点: `/set_group_portrait` 527 528 **参数** 529 530 | 字段 | 类型 | 说明 | 531 | ---------- | ------ | ------------------------ | 532 | `group_id` | int64 | 群号 | 533 | `file` | string | 图片文件名 | 534 | `cache` | int | 表示是否使用已缓存的文件 | 535 536 [1]`file` 参数支持以下几种格式： 537 538 - 绝对路径，例如 `file:///C:\\Users\Richard\Pictures\1.png`，格式使用 [`file` URI](https://tools.ietf.org/html/rfc8089) 539 - 网络 URL，例如 `http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg` 540 - Base64 541 编码，例如 `base64://iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAKElEQVQ4EWPk5+RmIBcwkasRpG9UM4mhNxpgowFGMARGEwnBIEJVAAAdBgBNAZf+QAAAAABJRU5ErkJggg==` 542 543 [2]`cache`参数: 通过网络 URL 发送时有效，`1`表示使用缓存，`0`关闭关闭缓存，默认 为`1` 544 545 [3] 目前这个API在登录一段时间后因cookie失效而失效，请考虑后使用 546 547 ### 获取图片信息 548 549 终结点: `/get_image` 550 551 > 该接口为 CQHTTP 接口修改 552 553 参数 554 555 | 字段 | 类型 | 说明 | 556 | ------ | ------ | -------------- | 557 | `file` | string | 图片缓存文件名 | 558 559 响应数据 560 561 | 字段 | 类型 | 说明 | 562 | ---------- | ------ | -------------- | 563 | `size` | int32 | 图片源文件大小 | 564 | `filename` | string | 图片文件原名 | 565 | `url` | string | 图片下载地址 | 566 567 ### 获取消息 568 569 终结点: `/get_msg` 570 571 参数 572 573 | 字段 | 类型 | 说明 | 574 | ------------ | ----- | ------ | 575 | `message_id` | int32 | 消息id | 576 577 响应数据 578 579 | 字段 | 类型 | 说明 | 580 | ------------ | ------- | ---------- | 581 | `message_id` | int32 | 消息id | 582 | `real_id` | int32 | 消息真实id | 583 | `sender` | object | 发送者 | 584 | `time` | int32 | 发送时间 | 585 | `message` | message | 消息内容 | 586 587 ### 获取合并转发内容 588 589 终结点: `/get_forward_msg` 590 591 参数 592 593 | 字段 | 类型 | 说明 | 594 | ------------ | ------ | ------ | 595 | `message_id` | string | 消息id | 596 597 响应数据 598 599 | 字段 | 类型 | 说明 | 600 | ---------- | ----------------- | -------- | 601 | `messages` | forward message[] | 消息列表 | 602 603 响应示例 604 605 ````json5 606 { 607 "data": { 608 "messages": [ 609 { 610 "content": "合并转发1", 611 "sender": { 612 "nickname": "发送者A", 613 "user_id": 10086 614 }, 615 "time": 1595694374 616 }, 617 { 618 "content": "合并转发2[CQ:image,file=xxxx,url=xxxx]", 619 "sender": { 620 "nickname": "发送者B", 621 "user_id": 10087 622 }, 623 "time": 1595694393 624 // 可选 625 } 626 ] 627 }, 628 "retcode": 0, 629 "status": "ok" 630 } 631 ```` 632 633 ### 发送合并转发(群/私聊) 634 635 终结点: `/send_group_forward_msg`, `send_private_forward_msg`, `send_forward_msg` 636 637 **参数** 638 639 | 字段 | 类型 | 说明 | 640 |------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| 641 | `group_id` | int64 | 群号 | 642 | `user_id` | int64 | 私聊QQ号 | 643 | `messages` | forward node[] | 自定义转发消息, 具体看 [CQCode](https://github.com/Mrs4s/go-cqhttp/blob/master/docs/cqhttp.md#%E5%90%88%E5%B9%B6%E8%BD%AC%E5%8F%91%E6%B6%88%E6%81%AF%E8%8A%82%E7%82%B9) | 644 645 响应数据 646 647 | 字段 | 类型 | 说明 | 648 | ------------ | ------ | ------ | 649 | `message_id` | string | 消息id | 650 651 ### 获取中文分词 652 653 终结点: `/.get_word_slices` 654 655 **参数** 656 657 | 字段 | 类型 | 说明 | 658 | --------- | ------ | ---- | 659 | `content` | string | 内容 | 660 661 **响应数据** 662 663 | 字段 | 类型 | 说明 | 664 | -------- | -------- | ---- | 665 | `slices` | string[] | 词组 | 666 667 ### 设置精华消息 668 669 终结点: `/set_essence_msg` 670 671 **参数** 672 673 | 字段 | 类型 | 说明 | 674 | ------------ | ----- | ------ | 675 | `message_id` | int32 | 消息ID | 676 677 **响应数据** 678 679 无 680 681 ### 移出精华消息 682 683 终结点: `/delete_essence_msg` 684 685 **参数** 686 687 | 字段 | 类型 | 说明 | 688 | ------------ | ----- | ------ | 689 | `message_id` | int32 | 消息ID | 690 691 **响应数据** 692 693 无 694 695 ### 获取精华消息列表 696 697 终结点: `/get_essence_msg_list` 698 699 **参数** 700 701 | 字段 | 类型 | 说明 | 702 | ---------- | ----- | ---- | 703 | `group_id` | int64 | 群号 | 704 705 **响应数据** 706 707 响应内容为 JSON 数组，每个元素如下： 708 709 | 字段名 | 数据类型 | 说明 | 710 | --------------- | -------- | ------------ | 711 | `sender_id` | int64 | 发送者QQ 号 | 712 | `sender_nick` | string | 发送者昵称 | 713 | `sender_time` | int64 | 消息发送时间 | 714 | `operator_id` | int64 | 操作者QQ 号 | 715 | `operator_nick` | string | 操作者昵称 | 716 | `operator_time` | int64 | 精华设置时间 | 717 | `message_id` | int32 | 消息ID | 718 719 ### 图片OCR 720 721 > 注意: 目前图片OCR接口仅支持接受的图片 722 723 终结点: `/ocr_image` 724 725 **参数** 726 727 | 字段 | 类型 | 说明 | 728 | ------- | ------ | ------ | 729 | `image` | string | 图片ID | 730 731 **响应数据** 732 733 | 字段 | 类型 | 说明 | 734 | ---------- | --------------- | ------- | 735 | `texts` | TextDetection[] | OCR结果 | 736 | `language` | string | 语言 | 737 738 **TextDetection** 739 740 | 字段 | 类型 | 说明 | 741 | ------------- | ------- | ------ | 742 | `text` | string | 文本 | 743 | `confidence` | int32 | 置信度 | 744 | `coordinates` | vector2 | 坐标 | 745 746 ### 获取群系统消息 747 748 终结点: `/get_group_system_msg` 749 750 **响应数据** 751 752 | 字段 | 类型 | 说明 | 753 | ------------------ | ---------------- | ------------ | 754 | `invited_requests` | InvitedRequest[] | 邀请消息列表 | 755 | `join_requests` | JoinRequest[] | 进群消息列表 | 756 757 > 注意: 如果列表不存在任何消息, 将返回 `null` 758 759 **InvitedRequest** 760 761 | 字段 | 类型 | 说明 | 762 | -------------- | ------ | ----------------- | 763 | `request_id` | int64 | 请求ID | 764 | `invitor_uin` | int64 | 邀请者 | 765 | `invitor_nick` | string | 邀请者昵称 | 766 | `group_id` | int64 | 群号 | 767 | `group_name` | string | 群名 | 768 | `checked` | bool | 是否已被处理 | 769 | `actor` | int64 | 处理者, 未处理为0 | 770 771 **JoinRequest** 772 773 | 字段 | 类型 | 说明 | 774 | ---------------- | ------ | ----------------- | 775 | `request_id` | int64 | 请求ID | 776 | `requester_uin` | int64 | 请求者ID | 777 | `requester_nick` | string | 请求者昵称 | 778 | `message` | string | 验证消息 | 779 | `group_id` | int64 | 群号 | 780 | `group_name` | string | 群名 | 781 | `checked` | bool | 是否已被处理 | 782 | `actor` | int64 | 处理者, 未处理为0 | 783 784 ### 获取群文件系统信息 785 786 终结点: `/get_group_file_system_info` 787 788 **参数** 789 790 | 字段 | 类型 | 说明 | 791 | ---------- | ----- | ---- | 792 | `group_id` | int64 | 群号 | 793 794 **响应数据** 795 796 | 字段 | 类型 | 说明 | 797 | ------------- | ----- | ---------- | 798 | `file_count` | int32 | 文件总数 | 799 | `limit_count` | int32 | 文件上限 | 800 | `used_space` | int64 | 已使用空间 | 801 | `total_space` | int64 | 空间上限 | 802 803 ### 获取群根目录文件列表 804 805 > `File` 和 `Folder` 对象信息请参考最下方 806 807 终结点: `/get_group_root_files` 808 809 **参数** 810 811 | 字段 | 类型 | 说明 | 812 | ---------- | ----- | ---- | 813 | `group_id` | int64 | 群号 | 814 815 **响应数据** 816 817 | 字段 | 类型 | 说明 | 818 | --------- | -------- | ---------- | 819 | `files` | File[] | 文件列表 | 820 | `folders` | Folder[] | 文件夹列表 | 821 822 ### 获取群子目录文件列表 823 824 > `File` 和 `Folder` 对象信息请参考最下方 825 826 终结点: `/get_group_files_by_folder` 827 828 **参数** 829 830 | 字段 | 类型 | 说明 | 831 | ----------- | ------ | --------------------------- | 832 | `group_id` | int64 | 群号 | 833 | `folder_id` | string | 文件夹ID 参考 `Folder` 对象 | 834 835 **响应数据** 836 837 | 字段 | 类型 | 说明 | 838 | --------- | -------- | ---------- | 839 | `files` | File[] | 文件列表 | 840 | `folders` | Folder[] | 文件夹列表 | 841 842 ### 获取群文件资源链接 843 844 > `File` 和 `Folder` 对象信息请参考最下方 845 846 终结点: `/get_group_file_url` 847 848 **参数** 849 850 | 字段 | 类型 | 说明 | 851 | ---------- | ------ | ------------------------- | 852 | `group_id` | int64 | 群号 | 853 | `file_id` | string | 文件ID 参考 `File` 对象 | 854 | `busid` | int32 | 文件类型 参考 `File` 对象 | 855 856 **响应数据** 857 858 | 字段 | 类型 | 说明 | 859 | ----- | ------ | ------------ | 860 | `url` | string | 文件下载链接 | 861 862 **File** 863 864 | 字段 | 类型 | 说明 | 865 | ---------------- | ------ | ---------------------- | 866 | `file_id` | string | 文件ID | 867 | `file_name` | string | 文件名 | 868 | `busid` | int32 | 文件类型 | 869 | `file_size` | int64 | 文件大小 | 870 | `upload_time` | int64 | 上传时间 | 871 | `dead_time` | int64 | 过期时间,永久文件恒为0 | 872 | `modify_time` | int64 | 最后修改时间 | 873 | `download_times` | int32 | 下载次数 | 874 | `uploader` | int64 | 上传者ID | 875 | `uploader_name` | string | 上传者名字 | 876 877 **Folder** 878 879 | 字段 | 类型 | 说明 | 880 | ------------------ | ------ | ---------- | 881 | `folder_id` | string | 文件夹ID | 882 | `folder_name` | string | 文件名 | 883 | `create_time` | int64 | 创建时间 | 884 | `creator` | int64 | 创建者 | 885 | `creator_name` | string | 创建者名字 | 886 | `total_file_count` | int32 | 子文件数量 | 887 888 ### 上传群文件 889 890 终结点: `/upload_group_file` 891 892 **参数** 893 894 | 字段 | 类型 | 说明 | 895 | ---------- | ------ | ------------------------- | 896 | `group_id` | int64 | 群号 | 897 | `file` | string | 本地文件路径 | 898 | `name` | string | 储存名称 | 899 | `folder` | string | 父目录ID | 900 901 > 在不提供 `folder` 参数的情况下默认上传到根目录 902 > 只能上传本地文件, 需要上传 `http` 文件的话请先调用 `download_file` API下载 903 904 ### 上传私聊文件 905 906 终结点: `/upload_private_file` 907 908 **参数** 909 910 | 字段 | 类型 | 说明 | 911 |-----------|--------|--------| 912 | `user_id` | int64 | 接收者id | 913 | `file` | string | 本地文件路径 | 914 | `name` | string | 储存名称 | 915 916 > 只能上传本地文件, 需要上传 `http` 文件的话请先调用 `download_file` API下载 917 918 ### 设置 QQ 个人资料 919 920 终结点: `/set_qq_profile` 921 922 **参数** 923 924 | 字段 | 类型 | 说明 | 925 |-----------------|--------|------| 926 | `nickname` | int64 | 昵称 | 927 | `company` | string | 公司 | 928 | `email` | string | 邮箱 | 929 | `college` | string | 大学 | 930 | `personal_note` | string | 个人签名 | 931 932 > 所有参数字段都为可选。 933 934 ### 获取状态 935 936 终结点: `/get_status` 937 938 **响应数据** 939 940 | 字段 | 类型 | 说明 | 941 | ----------------- | ---------- | ------------------------------- | 942 | `app_initialized` | bool | 原 `CQHTTP` 字段, 恒定为 `true` | 943 | `app_enabled` | bool | 原 `CQHTTP` 字段, 恒定为 `true` | 944 | `plugins_good` | bool | 原 `CQHTTP` 字段, 恒定为 `true` | 945 | `app_good` | bool | 原 `CQHTTP` 字段, 恒定为 `true` | 946 | `online` | bool | 表示BOT是否在线 | 947 | `good` | bool | 同 `online` | 948 | `stat` | Statistics | 运行统计 | 949 950 **Statistics** 951 952 | 字段 | 类型 | 说明 | 953 | ------------------ | ------ | ---------------- | 954 | `packet_received` | uint64 | 收到的数据包总数 | 955 | `packet_sent` | uint64 | 发送的数据包总数 | 956 | `packet_lost` | uint32 | 数据包丢失总数 | 957 | `message_received` | uint64 | 接受信息总数 | 958 | `message_sent` | uint64 | 发送信息总数 | 959 | `disconnect_times` | uint32 | TCP链接断开次数 | 960 | `lost_times` | uint32 | 账号掉线次数 | 961 962 > 注意: 所有统计信息都将在重启后重制 963 964 ### 获取群@全体成员剩余次数 965 966 终结点: `/get_group_at_all_remain` 967 968 **参数** 969 970 | 字段 | 类型 | 说明 | 971 | ---------- | ----- | ---- | 972 | `group_id` | int64 | 群号 | 973 974 **响应数据** 975 976 | 字段 | 类型 | 说明 | 977 | ------------------------------- | ----- | --------------------------------- | 978 | `can_at_all` | bool | 是否可以@全体成员 | 979 | `remain_at_all_count_for_group` | int16 | 群内所有管理当天剩余@全体成员次数 | 980 | `remain_at_all_count_for_uin` | int16 | BOT当天剩余@全体成员次数 | 981 982 ### 下载文件到缓存目录 983 984 终结点: `/download_file` 985 986 **参数** 987 988 | 字段 | 类型 | 说明 | 989 | -------------- | --------------- | ------------ | 990 | `url` | string | 链接地址 | 991 | `thread_count` | int32 | 下载线程数 | 992 | `headers` | string or array | 自定义请求头 | 993 994 **`headers`格式:** 995 996 字符串: 997 998 ``` 999 User-Agent=YOUR_UA[\r\n]Referer=https://www.baidu.com 1000 ``` 1001 1002 > `[\r\n]` 为换行符, 使用http请求时请注意编码 1003 1004 JSON数组: 1005 1006 ``` 1007 [ 1008 "User-Agent=YOUR_UA", 1009 "Referer=https://www.baidu.com", 1010 ] 1011 ``` 1012 1013 **响应数据** 1014 1015 | 字段 | 类型 | 说明 | 1016 | ------ | ------ | -------------------- | 1017 | `file` | string | 下载文件的*绝对路径* | 1018 1019 > 通过这个API下载的文件能直接放入CQ码作为图片或语音发送 1020 > 调用后会阻塞直到下载完成后才会返回数据，请注意下载大文件时的超时 1021 1022 ### 获取群消息历史记录 1023 1024 终结点：`/get_group_msg_history` 1025 1026 **参数** 1027 1028 | 字段 | 类型 | 说明 | 1029 | ------------- | ----- | ----------------------------------- | 1030 | `message_seq` | int64 | 起始消息序号, 可通过 `get_msg` 获得 | 1031 | `group_id` | int64 | 群号 | 1032 1033 **响应数据** 1034 1035 | 字段 | 类型 | 说明 | 1036 | ---------- | --------- | -------------------------- | 1037 | `messages` | []Message | 从起始序号开始的前19条消息 | 1038 1039 > 不提供起始序号将默认获取最新的消息 1040 1041 ### 获取当前账号在线客户端列表 1042 1043 终结点：`/get_online_clients` 1044 1045 **参数** 1046 1047 | 字段 | 类型 | 说明 | 1048 | ---------- | ---- | ------------ | 1049 | `no_cache` | bool | 是否无视缓存 | 1050 1051 **响应数据** 1052 1053 | 字段 | 类型 | 说明 | 1054 | --------- | -------- | -------------- | 1055 | `clients` | []Device | 在线客户端列表 | 1056 1057 **Device** 1058 1059 | 字段 | 类型 | 说明 | 1060 | ------------- | ------ | -------- | 1061 | `app_id` | int64 | 客户端ID | 1062 | `device_name` | string | 设备名称 | 1063 | `device_kind` | string | 设备类型 | 1064 1065 ### 检查链接安全性 1066 1067 终结点：`/check_url_safely` 1068 1069 **参数** 1070 1071 | 字段 | 类型 | 说明 | 1072 | ---------- | ------ | ------------------------- | 1073 | `url` | string | 需要检查的链接 | 1074 1075 **响应数据** 1076 1077 | 字段 | 类型 | 说明 | 1078 | ---------- | ---------- | ------------ | 1079 | `level` | int | 安全等级, 1: 安全 2: 未知 3: 危险 | 1080 1081 ### 获取用户VIP信息 1082 1083 终结点：`/_get_vip_info` 1084 1085 **参数** 1086 1087 | 字段名 | 数据类型 | 默认值 | 说明 | 1088 | --------- | -------- | ------ | ----- | 1089 | `user_id` | int64 | | QQ 号 | 1090 1091 **响应数据** 1092 1093 | 字段 | 类型 | 说明 | 1094 | ------------------ | ------- | ------------ | 1095 | `user_id` | int64 | QQ 号 | 1096 | `nickname` | string | 用户昵称 | 1097 | `level` | int64 | QQ 等级 | 1098 | `level_speed` | float64 | 等级加速度 | 1099 | `vip_level` | string | 会员等级 | 1100 | `vip_growth_speed` | int64 | 会员成长速度 | 1101 | `vip_growth_total` | int64 | 会员成长总值 | 1102 1103 ### 发送群公告 1104 1105 终结点： `/_send_group_notice` 1106 1107 **参数** 1108 1109 | 字段名 | 数据类型 | 默认值 | 说明 | 1110 | ---------- | -------- | ------ | -------- | 1111 | `group_id` | int64 | | 群号 | 1112 | `content` | string | | 公告内容 | 1113 1114 `该 API 没有响应数据` 1115 1116 ### 获取群公告 1117 1118 终结点： `/_get_group_notice` 1119 1120 **参数** 1121 1122 | 字段名 | 数据类型 | 默认值 | 说明 | 1123 | ---------- | -------- | ------ | -------- | 1124 | `group_id` | int64 | | 群号 | 1125 1126 **响应数据** 1127 1128 数组信息: 1129 1130 | 字段名 | 数据类型 | 默认值 | 说明 | 1131 |----------------|--------| ------ |-------| 1132 | `notice_id` | string | | 公告id | 1133 | `sender_id` | string | | 发布者id | 1134 | `publish_time` | string | | 发布时间 | 1135 | `message` | GroupNoticeMessage | | 公告id | 1136 1137 响应示例 1138 1139 ```json 1140 { 1141 "data": [ 1142 { 1143 "notice_id": "8850de2e00000000cc6bbd628a150c00", 1144 "sender_id": 1111111, 1145 "publish_time": 1656581068, 1146 "message": { 1147 "text": "这是一条公告", 1148 "images": [] 1149 } 1150 } 1151 ], 1152 "retcode": 0, 1153 "status": "ok" 1154 } 1155 ``` 1156 1157 ### 删除群公告 1158 1159 终结点： `/_del_group_notice` 1160 1161 **参数** 1162 1163 | 字段名 | 数据类型 | 默认值 | 说明 | 1164 |-------------| -------- | ------ |------| 1165 | `group_id` | int64 | | 群号 | 1166 | `notice_id` | string | | 公告id | 1167 1168 `该 API 没有响应数据` 1169 1170 ### 获取单向好友列表 1171 1172 终结点: `/get_unidirectional_friend_list` 1173 1174 **响应数据** 1175 1176 数组信息: 1177 1178 | 字段 | 类型 | 说明 | 1179 | ------------- | ------ | -------- | 1180 | `nickname` | string | 昵称 | 1181 | `user_id` | int64 | 用户QQ号 | 1182 | `source` | string | 添加途径 | 1183 1184 > 添加途径为用户显示内容, 如 `精确查找` `QQ群 - xxxx` 1185 1186 ### 删除单向好友 1187 1188 终结点: `/delete_unidirectional_friend` 1189 1190 **参数** 1191 1192 | 字段名 | 数据类型 | 默认值 | 说明 | 1193 | ---------- | -------- | ------ | -------- | 1194 | `user_id` | int64 | | 好友ID | 1195 1196 `该 API 没有响应数据` 1197 1198 ### 删除好友 1199 1200 终结点: `/delete_friend` 1201 1202 **参数** 1203 1204 | 字段名 | 数据类型 | 默认值 | 说明 | 1205 | ---------- | -------- | ------ | -------- | 1206 | `user_id` | int64 | | 好友ID | 1207 1208 `该 API 没有响应数据` 1209 1210 ### 获取企点账号信息 1211 1212 > 该API只有企点协议可用 1213 1214 终结点: `/qidian_get_account_info` 1215 1216 **响应数据** 1217 1218 | 字段 | 类型 | 说明 | 1219 | ------------------ | ------- | ------------ | 1220 | `master_id` | int64 | 父账号ID | 1221 | `ext_name` | string | 用户昵称 | 1222 | `create_time` | int64 | 账号创建时间 | 1223 1224 ### 标记消息已读 1225 1226 终结点: `/mark_msg_as_read` 1227 1228 **参数** 1229 1230 | 字段名 | 数据类型 | 默认值 | 说明 | 1231 | ---------- | -------- | ------ | -------- | 1232 | `message_id` | int32 | | 消息ID | 1233 1234 ### 重载事件过滤器 1235 1236 终结点：`/reload_event_filter` 1237 1238 `该 API 无需参数也没有响应数据` 1239 1240 ## 事件 1241 1242 ### 群消息撤回 1243 1244 **上报数据** 1245 1246 | 字段 | 类型 | 可能的值 | 说明 | 1247 | ------------- | ------ | -------------- | -------------- | 1248 | `post_type` | string | `notice` | 上报类型 | 1249 | `notice_type` | string | `group_recall` | 消息类型 | 1250 | `group_id` | int64 | | 群号 | 1251 | `user_id` | int64 | | 消息发送者id | 1252 | `operator_id` | int64 | | 操作者id | 1253 | `message_id` | int64 | | 被撤回的消息id | 1254 1255 ### 好友消息撤回 1256 1257 **上报数据** 1258 1259 | 字段 | 类型 | 可能的值 | 说明 | 1260 | ------------- | ------ | --------------- | -------------- | 1261 | `post_type` | string | `notice` | 上报类型 | 1262 | `notice_type` | string | `friend_recall` | 消息类型 | 1263 | `user_id` | int64 | | 好友id | 1264 | `message_id` | int64 | | 被撤回的消息id | 1265 1266 ## 好友戳一戳 1267 1268 **事件数据** 1269 1270 | 字段名 | 数据类型 | 可能的值 | 说明 | 1271 | ------------- | -------- | -------- | ------------ | 1272 | `post_type` | string | `notice` | 上报类型 | 1273 | `notice_type` | string | `notify` | 消息类型 | 1274 | `sub_type` | string | `poke` | 提示类型 | 1275 | `self_id` | int64 | | BOT QQ 号 | 1276 | `sender_id` | int64 | | 发送者 QQ 号 | 1277 | `user_id` | int64 | | 发送者 QQ 号 | 1278 | `target_id` | int64 | | 被戳者 QQ 号 | 1279 | `time` | int64 | | 时间 | 1280 1281 ### 群内戳一戳 1282 1283 > 注意：此事件无法在平板和手表协议上触发 1284 1285 **上报数据** 1286 1287 | 字段 | 类型 | 可能的值 | 说明 | 1288 | ------------- | ------ | -------- | -------- | 1289 | `post_type` | string | `notice` | 上报类型 | 1290 | `notice_type` | string | `notify` | 消息类型 | 1291 | `group_id` | int64 | | 群号 | 1292 | `sub_type` | string | `poke` | 提示类型 | 1293 | `user_id` | int64 | | 发送者id | 1294 | `target_id` | int64 | | 被戳者id | 1295 1296 ### 群红包运气王提示 1297 1298 > 注意：此事件无法在平板和手表协议上触发 1299 1300 **上报数据** 1301 1302 | 字段 | 类型 | 可能的值 | 说明 | 1303 | ------------- | ------ | ------------ | ------------ | 1304 | `post_type` | string | `notice` | 上报类型 | 1305 | `notice_type` | string | `notify` | 消息类型 | 1306 | `group_id` | int64 | | 群号 | 1307 | `sub_type` | string | `lucky_king` | 提示类型 | 1308 | `user_id` | int64 | | 红包发送者id | 1309 | `target_id` | int64 | | 运气王id | 1310 1311 ### 群成员荣誉变更提示 1312 1313 > 注意：此事件无法在平板和手表协议上触发 1314 1315 **上报数据** 1316 1317 | 字段 | 类型 | 可能的值 | 说明 | 1318 | ------------- | ------ | -------------------------------------------------------- | -------- | 1319 | `post_type` | string | `notice` | 上报类型 | 1320 | `notice_type` | string | `notify` | 消息类型 | 1321 | `group_id` | int64 | | 群号 | 1322 | `sub_type` | string | `honor` | 提示类型 | 1323 | `user_id` | int64 | | 成员id | 1324 | `honor_type` | string | `talkative:龙王` `performer:群聊之火` `emotion:快乐源泉` | 荣誉类型 | 1325 1326 ### 群成员名片更新 1327 1328 > 注意: 此事件不保证时效性，仅在收到消息时校验卡片 1329 1330 **上报数据** 1331 1332 | 字段 | 类型 | 可能的值 | 说明 | 1333 | ------------- | ------ | ------------ | -------- | 1334 | `post_type` | string | `notice` | 上报类型 | 1335 | `notice_type` | string | `group_card` | 消息类型 | 1336 | `group_id` | int64 | | 群号 | 1337 | `user_id` | int64 | | 成员id | 1338 | `card_new` | string | | 新名片 | 1339 | `card_old` | string | | 旧名片 | 1340 1341 > PS: 当名片为空时 `card_xx` 字段为空字符串, 并不是昵称 1342 1343 ### 群成员头衔更新事件 1344 1345 **上报数据** 1346 1347 | 字段 | 类型 | 可能的值 | 说明 | 1348 | ------------- | ------ | ------------ | -------- | 1349 | `post_type` | string | `notice` | 上报类型 | 1350 | `notice_type` | string | `notify` | 消息类型 | 1351 | `group_id` | int64 | | 群号 | 1352 | `user_id` | int64 | | 成员id | 1353 | `title` | string | | 新头衔 | 1354 1355 ### 接收到离线文件 1356 1357 **上报数据** 1358 1359 | 字段 | 类型 | 可能的值 | 说明 | 1360 | ------------- | ------ | -------------- | -------- | 1361 | `post_type` | string | `notice` | 上报类型 | 1362 | `notice_type` | string | `offline_file` | 消息类型 | 1363 | `user_id` | int64 | | 发送者id | 1364 | `file` | object | | 文件数据 | 1365 1366 **file object** 1367 1368 | 字段 | 类型 | 可能的值 | 说明 | 1369 | ------ | ------ | -------- | -------- | 1370 | `name` | string | | 文件名 | 1371 | `size` | int64 | | 文件大小 | 1372 | `url` | string | | 下载链接 | 1373 1374 ### 其他客户端在线状态变更 1375 1376 **上报数据** 1377 1378 | 字段 | 类型 | 可能的值 | 说明 | 1379 | ------------- | ------ | --------------- | ------------ | 1380 | `post_type` | string | `notice` | 上报类型 | 1381 | `notice_type` | string | `client_status` | 消息类型 | 1382 | `client` | Device | | 客户端信息 | 1383 | `online` | bool | | 当前是否在线 | 1384 1385 ### 精华消息 1386 1387 **上报数据** 1388 1389 | 字段 | 类型 | 可能的值 | 说明 | 1390 | ------------- | ------ | -------------- | -------------------------- | 1391 | `post_type` | string | `notice` | 上报类型 | 1392 | `notice_type` | string | `essence` | 消息类型 | 1393 | `sub_type` | string | `add`,`delete` | 添加为`add`,移出为`delete` | 1394 | `sender_id` | int64 | | 消息发送者ID | 1395 | `operator_id` | int64 | | 操作者ID | 1396 | `message_id` | int32 | | 消息ID |