Skip to content

群管理 API

本页列出群与好友管理类动作:踢人、禁言、设置管理员、群名片、群名、头衔、退群、精华消息、@全体剩余次数、群打卡、群公告、加好友请求处理、加群请求处理等。

快速索引

API描述
set_group_kick群踢人
set_group_ban群禁言
set_group_whole_ban群全员禁言
set_group_anonymous_ban匿名用户禁言
set_group_admin设置 / 取消群管理员
set_group_anonymous群匿名开关
set_group_card设置群名片
set_group_name设置群名
set_group_leave退群 / 解散群
set_group_special_title设置群专属头衔
set_essence_msg设置精华消息
delete_essence_msg移除精华消息
get_group_at_all_remain获取群 @全体 剩余次数
send_group_sign群打卡
send_group_notice发送群公告
set_friend_add_request处理加好友请求
set_group_add_request处理加群请求 / 邀请

群踢人

  • API: set_group_kick
  • 描述: 将指定成员移出群聊。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
user_idnumber | string-被踢成员 QQ 号
reject_add_requestbooleanfalse是否拒绝其后续加群请求
json
{
  "group_id": "<group_id>",
  "user_id": "<friend_id>"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_kick' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","user_id":"<friend_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_kick', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    user_id: '<friend_id>'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_kick",
    json={
        "group_id": "<group_id>",
        "user_id": "<friend_id>",
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_iduser_id
1500踢人失败,例如权限不足或服务器拒绝。

群禁言

  • API: set_group_ban
  • 描述: 禁言或解除禁言指定群成员。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
user_idnumber | string-成员 QQ 号
durationnumber | string1800禁言秒数;0 解除禁言
json
{
  "group_id": "<group_id>",
  "user_id": "<friend_id>",
  "duration": 600
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_ban' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","user_id":"<friend_id>","duration":600}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_ban', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    user_id: '<friend_id>',
    duration: 600
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_ban",
    json={
        "group_id": "<group_id>",
        "user_id": "<friend_id>",
        "duration": 600,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_iduser_id
1500禁言失败,例如权限不足或服务器拒绝。

注意事项

  • duration0 时解除禁言。

群全员禁言

  • API: set_group_whole_ban
  • 描述: 开启或关闭群全员禁言。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
enablebooleantrue是否开启全员禁言
json
{
  "group_id": "<group_id>",
  "enable": true
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_whole_ban' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","enable":true}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_whole_ban', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    enable: true
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_whole_ban",
    json={
        "group_id": "<group_id>",
        "enable": True,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_id
1500操作失败,例如权限不足。

匿名用户禁言

  • API: set_group_anonymous_ban
  • 描述: 禁言群内匿名用户。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
anonymousobject-消息事件中的匿名成员对象(取其 flag
anonymous_flagstring-匿名 flag 字符串(优先于 anonymous.flag
durationnumber | string1800禁言秒数

anonymous_flaganonymous.flag 至少提供一个。

json
{
  "group_id": "<group_id>",
  "anonymous_flag": "<flag>",
  "duration": 600
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_anonymous_ban' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","anonymous_flag":"<flag>","duration":600}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_anonymous_ban', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    anonymous_flag: '<flag>',
    duration: 600
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_anonymous_ban",
    json={
        "group_id": "<group_id>",
        "anonymous_flag": "<flag>",
        "duration": 600,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400缺少 anonymous_flaganonymous.flag
1500禁言失败。

设置 / 取消群管理员

  • API: set_group_admin
  • 描述: 设置或取消指定成员的群管理员身份。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
user_idnumber | string-成员 QQ 号
enablebooleantruetrue 设为管理员,false 取消管理员
json
{
  "group_id": "<group_id>",
  "user_id": "<friend_id>",
  "enable": true
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_admin' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","user_id":"<friend_id>","enable":true}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_admin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    user_id: '<friend_id>',
    enable: true
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_admin",
    json={
        "group_id": "<group_id>",
        "user_id": "<friend_id>",
        "enable": True,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_iduser_id
1500操作失败,例如非群主无权设置管理员。

群匿名开关

  • API: set_group_anonymous
  • 描述: 开启或关闭群匿名聊天。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
enablebooleantrue是否允许群内匿名
json
{
  "group_id": "<group_id>",
  "enable": true
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_anonymous' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","enable":true}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_anonymous', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    enable: true
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_anonymous",
    json={
        "group_id": "<group_id>",
        "enable": True,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_id
1500操作失败。

设置群名片

  • API: set_group_card
  • 描述: 设置指定成员的群名片(群备注)。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
user_idnumber | string-成员 QQ 号
cardstring""新名片
json
{
  "group_id": "<group_id>",
  "user_id": "<friend_id>",
  "card": "新名片"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_card' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","user_id":"<friend_id>","card":"新名片"}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    user_id: '<friend_id>',
    card: '新名片'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_card",
    json={
        "group_id": "<group_id>",
        "user_id": "<friend_id>",
        "card": "新名片",
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_iduser_id
1500操作失败。

注意事项

  • card 留空或省略时清除名片。

设置群名

  • API: set_group_name
  • 描述: 修改群名称。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
group_namestring-新群名
json
{
  "group_id": "<group_id>",
  "group_name": "新群名"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_name' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","group_name":"新群名"}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_name', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    group_name: '新群名'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_name",
    json={
        "group_id": "<group_id>",
        "group_name": "新群名",
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_idgroup_name
1500操作失败。

退群 / 解散群

  • API: set_group_leave
  • 描述: 退出群聊或解散群聊(需群主权限)。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
is_dismissbooleanfalsetrue 解散群(需群主),false 退群
json
{
  "group_id": "<group_id>"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_leave' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_leave', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_leave",
    json={"group_id": "<group_id>"},
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_id
1500操作失败。

设置群专属头衔

  • API: set_group_special_title
  • 描述: 设置指定成员的群专属头衔(需群主权限)。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
user_idnumber | string-成员 QQ 号
special_titlestring""头衔内容
durationnumber | string-1有效期秒数,-1 为永久
json
{
  "group_id": "<group_id>",
  "user_id": "<friend_id>",
  "special_title": "头衔"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_special_title' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","user_id":"<friend_id>","special_title":"头衔"}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_special_title', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    user_id: '<friend_id>',
    special_title: '头衔'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_special_title",
    json={
        "group_id": "<group_id>",
        "user_id": "<friend_id>",
        "special_title": "头衔",
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_iduser_id
1500操作失败。

注意事项

  • special_title 留空或省略时清除头衔。

设置精华消息

  • API: set_essence_msg
  • 描述: 将一条群消息设为精华消息。

请求参数

字段类型必填默认值说明
message_idstring-群消息 ID
json
{
  "message_id": "<message_id>"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_essence_msg' \
  -H 'Content-Type: application/json' \
  -d '{"message_id":"<message_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/set_essence_msg', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message_id: '<message_id>'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_essence_msg",
    json={"message_id": "<message_id>"},
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400message_id 非群消息或非法。
1500服务器拒绝。

注意事项

  • 仅群消息可设为精华。

移除精华消息

  • API: delete_essence_msg
  • 描述: 移除一条群精华消息。

请求参数

字段类型必填默认值说明
message_idstring-群消息 ID
json
{
  "message_id": "<message_id>"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/delete_essence_msg' \
  -H 'Content-Type: application/json' \
  -d '{"message_id":"<message_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/delete_essence_msg', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message_id: '<message_id>'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/delete_essence_msg",
    json={"message_id": "<message_id>"},
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400message_id 非群消息或非法。
1500服务器拒绝。

获取群 @全体 剩余次数

  • API: get_group_at_all_remain
  • 描述: 查询群内 @全体成员 的剩余可用次数。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
json
{
  "group_id": "<group_id>"
}

响应参数

字段类型说明备注
can_at_allboolean当前是否可以 @全体-
remain_at_all_count_for_groupnumber群内 @全体 剩余次数-
remain_at_all_count_for_uinnumber当前账号 @全体 剩余次数-
json
{
  "can_at_all": true,
  "remain_at_all_count_for_group": 10,
  "remain_at_all_count_for_uin": 5
}

示例

bash
curl -X POST 'http://127.0.0.1:5700/get_group_at_all_remain' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/get_group_at_all_remain', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>'
  })
})

const body = await res.json()
console.log(body.data.remain_at_all_count_for_uin)

错误码

retcode说明
1400参数错误,例如缺少 group_id
1500查询失败。

群打卡

  • API: send_group_sign
  • 描述: 在指定群执行打卡(签到)。

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
json
{
  "group_id": "<group_id>"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/send_group_sign' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>"}'
js
const res = await fetch('http://127.0.0.1:5700/send_group_sign', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/send_group_sign",
    json={"group_id": "<group_id>"},
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_id
1500打卡失败,例如服务器拒绝。

发送群公告

  • API: send_group_notice
  • 描述: 发送群公告。同时接受别名 _send_group_notice

请求参数

字段类型必填默认值说明
group_idnumber | string-群号
contentstring-公告内容
imagestring-图片(当前仅支持文字公告,图片参数保留但不生效)
json
{
  "group_id": "<group_id>",
  "content": "公告内容"
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/send_group_notice' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"<group_id>","content":"公告内容"}'
js
const res = await fetch('http://127.0.0.1:5700/send_group_notice', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    group_id: '<group_id>',
    content: '公告内容'
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/send_group_notice",
    json={
        "group_id": "<group_id>",
        "content": "公告内容",
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400参数错误,例如缺少 group_idcontent
1500发送失败,例如服务器拒绝。

注意事项

  • 当前仅支持纯文字公告,image 参数被接收但不生效。

处理加好友请求

  • API: set_friend_add_request
  • 描述: 同意或拒绝一条加好友请求。

请求参数

字段类型必填默认值说明
flagstring-请求事件携带的 flag
approvebooleantrue是否同意
remarkstring""同意后的好友备注
json
{
  "flag": "<flag>",
  "approve": true
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_friend_add_request' \
  -H 'Content-Type: application/json' \
  -d '{"flag":"<flag>","approve":true}'
js
const res = await fetch('http://127.0.0.1:5700/set_friend_add_request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flag: '<flag>',
    approve: true
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_friend_add_request",
    json={
        "flag": "<flag>",
        "approve": True,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400flag 非法。
1500操作失败,例如服务器拒绝。

处理加群请求 / 邀请

  • API: set_group_add_request
  • 描述: 同意或拒绝一条加群请求或入群邀请。

请求参数

字段类型必填默认值说明
flagstring-请求事件携带的 flag
sub_typestring-add(申请加群)或 invite(邀请入群)
approvebooleantrue是否同意
reasonstring""拒绝理由
json
{
  "flag": "<flag>",
  "sub_type": "add",
  "approve": true
}

响应参数

成功时 datanull

示例

bash
curl -X POST 'http://127.0.0.1:5700/set_group_add_request' \
  -H 'Content-Type: application/json' \
  -d '{"flag":"<flag>","sub_type":"add","approve":true}'
js
const res = await fetch('http://127.0.0.1:5700/set_group_add_request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flag: '<flag>',
    sub_type: 'add',
    approve: true
  })
})

const body = await res.json()
console.log(body.status)
py
import requests

resp = requests.post(
    "http://127.0.0.1:5700/set_group_add_request",
    json={
        "flag": "<flag>",
        "sub_type": "add",
        "approve": True,
    },
    timeout=10,
)
resp.raise_for_status()
body = resp.json()
print(body["status"])

错误码

retcode说明
1400flag 非法。
1500操作失败,例如服务器拒绝。