跳转到正文
群聊事件

群请求

GROUP_EVENT_REQUEST("group_request"):收到待处理的入群申请或邀请,及 handle_group_request 处理方法。

通过 on_group_event 推送,event_type 为 GROUP_EVENT_REQUEST("group_request")。event_time 为请求时间(Unix 秒)。接收事件本身不会自动同意、拒绝、标记已读或更改群成员。

参与人对应关系

由 data.kind 决定 operator_* 与 target_* 的含义:

data.kind含义operator_*target_*调用 handle_group_request 时 user_id
"join"主动申请入群申请人0 / ""operator_user_id
"invited_join"成员邀请他人入群,待管理员审核邀请人受邀人target_user_id
"invite"邀请 Bot 入群邀请人受邀 Bottarget_user_id

邀请人信息未取得时可为 0 / "";不能把收到通知的 Bot 当作未提供的参与人。

data 字段说明

字段类型说明
request_sequint64请求关联标识;原样保留,读取时注意 64 位整数精度,不自行生成或换算
kindstring请求类型:"join" / "invited_join" / "invite"
filteredbool是否属于被过滤/可疑请求,不改变主动人、被动人含义
descriptionstring申请说明,未提供为 ""
commentstring验证附言,未提供为 ""
sourcestring来源说明,未提供为 ""
warningstring风险提示,未提供为 ""
actionsGroupRequestAction[]可用操作数组,无操作时为 []
message_type / request_type / source_id / sub_source_id / group_message_typeuint32不透明处理上下文,随完整 data 原样保留
group_payloadstring(可选)十六进制不透明请求凭据,未提供时省略(非 null),可能为 "",须原样保留

可用操作 GroupRequestAction

字段类型说明
namestring操作名称,可能为空
labelstring详细按钮文案,可能为空
resultstring操作结果文案(不表示已执行或成功)
actionuint32不透明处理上下文,随完整 data 原样保留
payloadstring(可选)十六进制不透明动作凭据,未提供时省略(非 null),不要自行构造、解析或修改

操作顺序不固定,不要按数组位置判断同意或拒绝。

以下仅演示 JSON 结构(标识与凭据均为演示值,实际调用必须传入收到的完整原始 data):

{
  "request_seq": 1000000000000000,
  "message_type": 2,
  "request_type": 1,
  "source_id": 0,
  "sub_source_id": 0,
  "group_message_type": 1,
  "kind": "join",
  "filtered": false,
  "description": "申请入群",
  "comment": "你好",
  "source": "",
  "warning": "",
  "actions": [
    { "name": "同意", "label": "同意", "result": "已同意", "action": 0, "payload": "00" },
    { "name": "拒绝", "label": "拒绝", "result": "已拒绝", "action": 0, "payload": "00" }
  ],
  "group_payload": ""
}

处理接口:handle_group_request

const HandleGroupRequestResult *handle_group_request(
    uint64_t self_id, const char *platform, uint64_t group_id, uint64_t user_id,
    const char *data, bool approve);

void free_handle_group_request_result(const HandleGroupRequestResult *result);
  • 权限:handle_group_request(账号必须在线,须在插件工作线程调用)
  • 参数要求:
    • self_id、platform、group_id 取自同一次事件,其中 platform 为 PLATFORM_*,self_id、group_id、user_id 均不能为 0;user_id 按上表取待入群者 QQ 号,不要错传邀请人。
    • data 必须传入事件提供的完整原始 UTF-8 JSON 字符串,不要只保存 request_seq 或重新拼接,不得混用不同事件的参数。
    • approve:true 同意,false 普通拒绝(不拉黑、不忽略、不额外删除或标记已读)。
  • 返回 HandleGroupRequestResult:code == 0 表示服务器确认成功(message 可能为空);失败时检查 code 与 error(本地失败为 RESULT_LOCAL_ERROR)。避免重复或并发提交;网络失败时先核实状态再决定是否重试。
const HandleGroupRequestResult *result =
    handle_group_request(self_id, platform, group_id, user_id, data, approve);
if (result == NULL) {
    /* 当前客户端无法提供此接口,不能当作处理成功 */
} else {
    if (result->code == 0) {
        /* 服务器确认成功;result->message 可能为空 */
    } else {
        /* 读取 result->code 和 result->error 报告失败 */
    }
    free_handle_group_request_result(result);
}

GroupEvent 公共字段

字段类型说明
self_iduint64_t接收事件的 Bot 账号
platformconst char *所属平台 PLATFORM_*
event_typeconst char *事件类型 GROUP_EVENT_*
event_timeuint64_t事件时间(Unix 秒)
dataconst char *对应事件类型的 UTF-8 JSON 字符串
operator_nicknameconst char *主动人显示名(优先备注),未取得为 ""
operator_user_iduint64_t主动人 QQ 号,未取得或不适用时为 0
target_nicknameconst char *被动人显示名(优先备注),未取得为 ""
target_user_iduint64_t被动人 QQ 号,未取得或不适用时为 0
group_iduint64_t群号
group_nameconst char *群名称,未取得为 ""

本页目录