跳转到正文
好友事件

好友申请

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_sequint64申请关联标识;原样保留,读取时注意 64 位整数精度,不自行生成或换算
kindstring"verification"(验证申请)、"add_back"(可加回好友)、"unknown"(未识别类型)
nicknamestring申请人昵称(非备注),未提供为 ""
descriptionstring申请说明,未提供为 ""
commentstring验证附言,未提供为 ""
sourcestring来源说明,未提供为 ""
group_iduint64来源群号,无来源群时为 0
group_namestring来源群名称,无来源群时为 ""
actionsFriendRequestAction[]操作数组,无操作时为 []
message_type / request_type / source_id / sub_source_id / group_message_typeuint32不透明处理上下文,必须随完整 data 原样保留

可用操作 FriendRequestAction

字段类型说明
namestring简短操作名称
labelstring详细按钮文案
payloadstring(可选)十六进制不透明动作凭据;未提供时省略(非 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_iduint64_t接收事件的 Bot 账号
platformconst char *所属平台 PLATFORM_*
event_typeconst char *事件类型 FRIEND_EVENT_*
event_timeuint64_t服务端事件时间(Unix 秒)
dataconst char *对应事件类型的 UTF-8 JSON 字符串
operator_nicknameconst char *主动者显示名(优先备注,其次昵称),无可用名时为 ""
operator_user_iduint64_t主动者 QQ 号
target_nicknameconst char *被动者显示名(优先备注),不适用时为 ""
target_user_iduint64_t被动者 QQ 号,不适用时为 0

本页目录