群聊事件
群请求
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 入群 | 邀请人 | 受邀 Bot | target_user_id |
邀请人信息未取得时可为 0 / "";不能把收到通知的 Bot 当作未提供的参与人。
data 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
request_seq | uint64 | 请求关联标识;原样保留,读取时注意 64 位整数精度,不自行生成或换算 |
kind | string | 请求类型:"join" / "invited_join" / "invite" |
filtered | bool | 是否属于被过滤/可疑请求,不改变主动人、被动人含义 |
description | string | 申请说明,未提供为 "" |
comment | string | 验证附言,未提供为 "" |
source | string | 来源说明,未提供为 "" |
warning | string | 风险提示,未提供为 "" |
actions | GroupRequestAction[] | 可用操作数组,无操作时为 [] |
message_type / request_type / source_id / sub_source_id / group_message_type | uint32 | 不透明处理上下文,随完整 data 原样保留 |
group_payload | string(可选) | 十六进制不透明请求凭据,未提供时省略(非 null),可能为 "",须原样保留 |
可用操作 GroupRequestAction
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 操作名称,可能为空 |
label | string | 详细按钮文案,可能为空 |
result | string | 操作结果文案(不表示已执行或成功) |
action | uint32 | 不透明处理上下文,随完整 data 原样保留 |
payload | string(可选) | 十六进制不透明动作凭据,未提供时省略(非 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_id | uint64_t | 接收事件的 Bot 账号 |
platform | const char * | 所属平台 PLATFORM_* |
event_type | const char * | 事件类型 GROUP_EVENT_* |
event_time | uint64_t | 事件时间(Unix 秒) |
data | const char * | 对应事件类型的 UTF-8 JSON 字符串 |
operator_nickname | const char * | 主动人显示名(优先备注),未取得为 "" |
operator_user_id | uint64_t | 主动人 QQ 号,未取得或不适用时为 0 |
target_nickname | const char * | 被动人显示名(优先备注),未取得为 "" |
target_user_id | uint64_t | 被动人 QQ 号,未取得或不适用时为 0 |
group_id | uint64_t | 群号 |
group_name | const char * | 群名称,未取得为 "" |