好友事件
好友申请
FRIEND_EVENT_REQUEST("friend_request"):收到好友申请或添加提醒,及 handle_friend_request 处理方法。
通过 on_friend_event 推送,event_type 为 FRIEND_EVENT_REQUEST("friend_request")。operator_* 为申请人,target_* 为接收 Bot,event_time 为申请时间。接收事件不会自动同意、拒绝或标记已读。
data 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
request_seq | uint64 | 申请关联标识;原样保留,读取时注意 64 位整数精度,不自行生成或换算 |
kind | string | "verification"(验证申请)、"add_back"(可加回好友)、"unknown"(未识别类型) |
nickname | string | 申请人昵称(非备注),未提供为 "" |
description | string | 申请说明,未提供为 "" |
comment | string | 验证附言,未提供为 "" |
source | string | 来源说明,未提供为 "" |
group_id | uint64 | 来源群号,无来源群时为 0 |
group_name | string | 来源群名称,无来源群时为 "" |
actions | FriendRequestAction[] | 操作数组,无操作时为 [] |
message_type / request_type / source_id / sub_source_id / group_message_type | uint32 | 不透明处理上下文,必须随完整 data 原样保留 |
可用操作 FriendRequestAction
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 简短操作名称 |
label | string | 详细按钮文案 |
payload | string(可选) | 十六进制不透明动作凭据;未提供时省略(非 null),提供为空串时保留原样,不要自行构造、解析或修改 |
以下仅演示 JSON 结构(标识和凭据均为演示值,实际调用必须使用收到的完整原始 data):
{
"request_seq": 1000000000000000,
"message_type": 1,
"request_type": 9,
"source_id": 2004,
"sub_source_id": 13,
"group_message_type": 0,
"kind": "add_back",
"nickname": "示例用户",
"description": "已添加你为好友",
"comment": "",
"source": "QQ群-示例群",
"group_id": 123456789,
"group_name": "示例群",
"actions": [
{ "name": "添加", "label": "加为好友", "payload": "00" }
]
}处理接口:handle_friend_request
const HandleFriendRequestResult *handle_friend_request(
uint64_t self_id, const char *platform, uint64_t user_id,
const char *data, bool approve);
void free_handle_friend_request_result(const HandleFriendRequestResult *result);- 权限:
handle_friend_request(账号必须在线,须在插件工作线程调用) - 参数要求:
self_id、platform、user_id分别取自同一次friend_request事件的self_id、platform、operator_user_id。data必填,必须传入事件提供的完整原始 UTF-8 JSON 字符串;不要只取request_seq,也不要重新拼接或修改处理上下文。approve:true同意或加回,false普通拒绝(不额外拉黑,不修改备注或好友分组)。不支持的动作返回RESULT_LOCAL_ERROR(如只有“添加”的add_back不能传false)。
- 返回
HandleFriendRequestResult:code == 0表示服务器确认成功(message可能为空);失败时检查code与error。避免对同一申请重复或并发提交;网络失败时先核实状态再决定是否重试。
const HandleFriendRequestResult *result =
handle_friend_request(self_id, platform, user_id, data, approve);
if (result) {
/* 检查 result->code,读取 result->error 或 result->message */
free_handle_friend_request_result(result);
}FriendEvent 公共字段
| 字段 | 类型 | 说明 |
|---|---|---|
self_id | uint64_t | 接收事件的 Bot 账号 |
platform | const char * | 所属平台 PLATFORM_* |
event_type | const char * | 事件类型 FRIEND_EVENT_* |
event_time | uint64_t | 服务端事件时间(Unix 秒) |
data | const char * | 对应事件类型的 UTF-8 JSON 字符串 |
operator_nickname | const char * | 主动者显示名(优先备注,其次昵称),无可用名时为 "" |
operator_user_id | uint64_t | 主动者 QQ 号 |
target_nickname | const char * | 被动者显示名(优先备注),不适用时为 "" |
target_user_id | uint64_t | 被动者 QQ 号,不适用时为 0 |