API相关
API相关文档
NapCat API参考
官方完整文档地址：https://docs.napneko.cn（建议优先查阅官方文档获取最新接口信息）
对接原理
GracyBot通过HTTP协议与NapCat实现通信，核心流程如下：
NapCat接收QQ消息 → 通过HTTP POST发送到GracyBot的/callback接口 → GracyBot处理消息 → 调用NapCat的HTTP API发送回复消息
常用API接口
以下为GracyBot开发中高频使用的NapCat API接口（基础URL通过配置文件NAPCAT_HTTP_URL定义）：
# 发送私聊消息
NAPCAT_HTTP_URL + "/send_private_msg"
# 发送群聊消息
NAPCAT_HTTP_URL + "/send_group_msg"
# 处理好友请求
NAPCAT_HTTP_URL + "/set_friend_add_request"
# 处理群邀请
NAPCAT_HTTP_URL + "/set_group_add_request"
消息格式
NapCat向GracyBot推送消息时，默认使用Array格式的JSON结构，核心字段包含：
{
"post_type": "message", // 消息类型（message/request/notice等）
"message_type": "private/group", // 消息场景（私聊/群聊）
"user_id": 12345678, // 发送者QQ号（私聊场景）
"group_id": 87654321, // 群号（群聊场景）
"raw_message": "你好，机器人！", // 原始消息内容
"message": [{"type": "text", "data": {"text": "你好，机器人！"}}], // 结构化消息
"time": 1699999999, // 消息时间戳
"self_id": 98765432 // 机器人自身QQ号
}
接口调用示例（Python）
以下为GracyBot中调用NapCat API发送私聊消息的简化示例：
import requests
import json
from core.config import NAPCAT_HTTP_URL
def send_private_msg(user_id, message):
"""
发送私聊消息
:param user_id: 接收者QQ号
:param message: 消息内容（文本/结构化消息）
:return: 接口响应结果
"""
url = f"{NAPCAT_HTTP_URL}/send_private_msg"
data = {
"user_id": user_id,
"message": message,
"auto_escape": False # 是否自动转义特殊字符
}
headers = {"Content-Type": "application/json"}
try:
response = requests.post(url, data=json.dumps(data), headers=headers, timeout=10)
return response.json()
except Exception as e:
print(f"发送私聊消息失败：{str(e)}")
return None
# 调用示例
send_private_msg(12345678, "这是一条通过API发送的私聊消息～")
📝 注意：API调用需确保NapCat服务已启动且HTTP接口正常，若出现调用失败，可先通过curl命令测试接口连通性，或查看NapCat日志排查问题。