官方QQ机器人框架——PHP代码【支持并发多台QQ机器人】

采用HTTPS回调参数进行QQ机器人控制

将文件上传至服务器

需要配置如下：

1. PHP8.0以上版本、ICP备案【海外服务器可不需要备案】
2. PHP扩展安装【redis】
3. 在qqbot.php中配置reids数据库【IP、密码】
4. 在data目录下创建关于机器人appid的PHP文件【{appid}.php】（代码在下方）
5. 在QQ机器人平台中【开发-回调配置-配置事件回调地址】配置指定到qqbot.php文件【https://{域名}/qqbot.php】

<?php
// 机器人配置信息
$BOT_CONFIG = [
    'appid'        => '{appid}',
    'bot_secret'   => '{appseret}', // 机器人唯一签名密钥
];

class BotHandler
{
    /**
     * 处理转发的请求数据
     * @param string $event_type 事件类型
     * @param array $event_data 事件数据
     */
    public function event_handle( string $event_type, array $event_data): array
    {
        // 事件分发
        switch ($event_type) {
            case 'GROUP_AT_MESSAGE_CREATE':
                $result = $result = [
                    'status' => 'success',
                    'msg' => 'QQ群信息处理',
                    'event_type' => $event_data
                ];
                break;
            default:
                $result = [
                    'status' => 'success',
                    'msg' => '未配置专属处理，默认接收',
                    'event_type' => $event_type
                ];
                break;
        }
        return $result; // 返回处理结果
    }
?>

$event_type参数

- GUILD_CREATE // 当机器人加入新guild时 
- GUILD_UPDATE // 当guild资料发生变更时 
- GUILD_DELETE // 当机器人退出guild时 
- CHANNEL_CREATE // 当channel被创建时 
- CHANNEL_UPDATE // 当channel被更新时 
- CHANNEL_DELETE // 当channel被删除时 
- GUILD_MEMBER_ADD // 当成员加入时 
- GUILD_MEMBER_UPDATE // 当成员资料变更时 
- GUILD_MEMBER_REMOVE // 当成员被移除时 
- MESSAGE_CREATE // 发送消息事件，代表频道内的全部消息，而不只是 at 机器人的消息。内容与 AT_MESSAGE_CREATE 相同 
- MESSAGE_DELETE // 删除（撤回）消息事件 
- MESSAGE_REACTION_ADD // 为消息添加表情表态 
- MESSAGE_REACTION_REMOVE // 为消息删除表情表态 
- DIRECT_MESSAGE_CREATE // 当收到用户发给机器人的私信消息时 - DIRECT_MESSAGE_DELETE // 删除（撤回）消息事件 
- C2C_MESSAGE_CREATE // 用户单聊发消息给机器人时候 
- FRIEND_ADD // 用户添加使用机器人 
- FRIEND_DEL // 用户删除机器人 
- C2C_MSG_REJECT // 用户在机器人资料卡手动关闭"主动消息"推送 
- C2C_MSG_RECEIVE // 用户在机器人资料卡手动开启"主动消息"推送开关 
- GROUP_AT_MESSAGE_CREATE // 用户在群里@机器人时收到的消息 
- GROUP_ADD_ROBOT // 机器人被添加到群聊 
- GROUP_DEL_ROBOT // 机器人被移出群聊 
- GROUP_MSG_REJECT // 群管理员主动在机器人资料页操作关闭通知 
- GROUP_MSG_RECEIVE // 群管理员主动在机器人资料页操作开启通知 
- INTERACTION_CREATE // 互动事件创建时 
- MESSAGE_AUDIT_PASS // 消息审核通过 
- MESSAGE_AUDIT_REJECT // 消息审核不通过 
- FORUM_THREAD_CREATE // 当用户创建主题时 
- FORUM_THREAD_UPDATE // 当用户更新主题时 
- FORUM_THREAD_DELETE // 当用户删除主题时 
- FORUM_POST_CREATE // 当用户创建帖子时 
- FORUM_POST_DELETE // 当用户删除帖子时 
- FORUM_REPLY_CREATE // 当用户回复评论时 
- FORUM_REPLY_DELETE // 当用户回复评论时 
- FORUM_PUBLISH_AUDIT_RESULT // 当用户发表审核通过时 
- AUDIO_START // 音频开始播放时 
- AUDIO_FINISH // 音频播放结束时 
- AUDIO_ON_MIC // 上麦时 
- AUDIO_OFF_MIC // 下麦时 
- AT_MESSAGE_CREATE // 当收到@机器人的消息时 
- PUBLIC_MESSAGE_DELETE // 当频道的消息被删除时

$event_data参数

群聊@消息格式
{
"id":"ROBOT1.0_uGVZKyFV24en16RWBfP89uvNS.tG5JRlql3JvwrFOCFnKkWmtuJwHsyD84.h5e.lDDwxA1yYkY0XObJLzwK74YKhpQ3NeXjU2.ZlHFWYyOk!",【消息ID（作为被动消息返回ID）】
"content":" \/绑定 \nzx5c3\n",【消息内容】
"timestamp":"2025-11-10T09:25:40+08:00",【接收消息时间】
"author":{
"id":"4780276D8AF7665940D5E9F33DC6CD9C",
"member_openid":"4780276D8AF7665940D5E9F33DC6CD9C",
"union_openid":"4780276D8AF7665940D5E9F33DC6CD9C"【用户ID】
},
"group_id":"F3BF46B140825DF2AE89957D9D244E16",
"group_openid":"F3BF46B140825DF2AE89957D9D244E16",【群聊ID】
"message_scene":{
"source":"default"
},
"message_type":0【消息类型】
}

可调用代码

/**
 * 发送群组消息的POST请求方法
 * @param string $group_openid 群组ID
 * @param string $acctoken access_token
 * @param string $content 消息内容（必填）
 * @param int $msg_type 消息类型：0文本，2markdown，3ark，4embed，7media（必填）
 * @param string $msg_id 前置收到的用户发送过来的消息ID，用于发送被动消息（回复）
 * @param int $msg_seq 回复消息的序号，与msg_id联合使用
 * @param array $markdown Markdown对象（可选）
 * @param array $keyboard Keyboard对象（可选）
 * @param array $media 富媒体群聊的file_info（可选）
 * @param array $ark Ark对象（可选）
 * @param string $event_id 前置收到的事件ID，用于发送被动消息（可选）
 * @return array 响应结果数组，包含status、data和error信息
 */
function send_group_message(string $group_openid, string $acctoken, string $content, int $msg_type, string $msg_id = '', int $msg_seq = 1, array $markdown = [], array $keyboard = [], array $media = [], array $ark = [], string $event_id = '')

/**
 * 发送单聊消息的POST请求方法
 * @param string $openid QQ用户的openid
 * @param string $acctoken access_token
 * @param int $msg_type 消息类型：0文本，2markdown，3ark，4embed，7media（必填）
 * @param string $content 消息内容（可选，文本消息必填）
 * @param string $msg_id 前置收到的用户发送过来的消息ID，用于发送被动消息（回复）
 * @param int $msg_seq 回复消息的序号，与msg_id联合使用
 * @param array $markdown Markdown对象（可选）
 * @param array $keyboard Keyboard对象（可选）
 * @param array $ark Ark对象（可选）
 * @param array $media 富媒体单聊的file_info（可选）
 * @param string $event_id 前置收到的事件ID，用于发送被动消息（可选）
 * @return array 响应结果数组，包含status、data和error信息
 */
function send_user_message(string $openid, string $acctoken, int $msg_type, string $content = '', string $msg_id = '', int $msg_seq = 1, array $markdown = [], array $keyboard = [], array $ark = [], array $media = [], string $event_id = '')