n8n-nodes-qq-guild-bot

QQ频道机器人的n8n节点包，支持发送消息和接收消息触发器。

功能特性

• ✅ 发送消息节点：向QQ频道发送文本、Markdown、Embed等多种类型的消息
• ✅ 接收消息触发器：监听QQ频道消息事件，自动触发n8n工作流
• ✅ 完整的类型支持：基于TypeScript开发，提供完整的类型定义
• ✅ 易于配置：简单的凭证配置，快速接入QQ频道机器人

安装

在n8n中安装

方式1：通过n8n社区节点安装（推荐）

1. 打开n8n实例
2. 进入 Settings > Community Nodes
3. 点击 Install a community node
4. 输入 n8n-nodes-qq-guild-bot
5. 点击 Install

方式2：通过npm安装

# 进入n8n安装目录
cd ~/.n8n

# 安装节点包
npm install n8n-nodes-qq-guild-bot

# 重启n8n

配置

获取QQ频道机器人凭证

1. 访问 QQ开放平台
2. 登录并创建机器人应用
3. 在应用详情页获取以下信息：
   • 应用ID (AppID)：机器人的唯一标识
   • 机器人令牌 (Token)：用于API认证的密钥

在n8n中配置凭证

1. 在n8n工作流编辑器中，添加QQ频道机器人节点
2. 点击 Credential to connect with
3. 选择 Create New
4. 填写凭证信息：
   • 应用ID：填入从QQ开放平台获取的AppID
   • 机器人令牌：填入从QQ开放平台获取的Token
   • 沙箱环境：开发测试时可勾选，生产环境请取消勾选
5. 点击 Save 保存凭证

使用

发送消息节点

基本用法

1. 在工作流中添加 QQ频道机器人 节点
2. 选择已配置的凭证
3. 配置参数：
   • 操作：选择"发送消息"
   • 子频道ID：要发送消息的子频道ID
   • 消息类型：选择文本、Markdown或Embed
   • 消息内容：输入要发送的内容

发送文本消息

{
  "operation": "sendMessage",
  "channelId": "123456789",
  "messageType": "text",
  "content": "Hello from n8n!"
}

发送Markdown消息

{
  "operation": "sendMessage",
  "channelId": "123456789",
  "messageType": "markdown",
  "content": "# 标题\n\n这是一条**Markdown**消息"
}

发送Embed消息

{
  "operation": "sendMessage",
  "channelId": "123456789",
  "messageType": "embed",
  "embed": {
    "title": "通知标题",
    "description": "这是一条Embed消息",
    "thumbnail": "https://example.com/image.png"
  }
}

接收消息触发器

基本用法

1. 在工作流中添加 QQ频道消息触发器 节点作为起始节点
2. 选择已配置的凭证
3. 配置参数：
   • 事件类型：选择要监听的消息类型
     • @消息：仅接收@机器人的消息
     • 频道消息：接收所有频道消息（需要权限）
     • 私信消息：接收私信消息

工作流示例

QQ频道消息触发器 → 条件判断 → 发送回复消息

当接收到消息时，触发器会输出以下数据结构：

{
  "id": "消息ID",
  "content": "消息内容",
  "author": {
    "id": "用户ID",
    "username": "用户名"
  },
  "channel_id": "子频道ID",
  "guild_id": "频道ID",
  "timestamp": "2024-01-01T00:00:00Z"
}

常见问题

Q: 如何获取子频道ID？

A: 在QQ频道客户端中，右键点击子频道，选择"复制子频道ID"。

Q: 为什么触发器没有接收到消息？

A: 请检查以下几点：

1. 确认机器人已被添加到对应的频道
2. 确认机器人有相应的权限（如接收消息权限）
3. 如果选择"频道消息"事件，需要在QQ开放平台开通"消息事件"权限
4. 检查n8n工作流是否处于激活状态

Q: 发送消息失败，提示认证错误？

A: 请检查：

1. AppID和Token是否正确
2. Token是否已过期
3. 是否选择了正确的沙箱环境选项

Q: 支持发送图片吗？

A: 支持。可以在消息中添加图片URL，或使用Embed消息类型设置缩略图。

开发

本地开发

# 克隆仓库
git clone https://github.com/yourusername/n8n-nodes-qq-guild-bot.git
cd n8n-nodes-qq-guild-bot

# 安装依赖
npm install

# 构建
npm run build

# 监听模式（开发时使用）
npm run dev

项目结构

n8n-nodes-qq-guild-bot/
├── credentials/           # 凭证定义
├── nodes/                 # 节点定义
│   ├── QqGuildBot/       # 发送消息节点
│   └── QqGuildBotTrigger/ # 触发器节点
├── lib/                   # SDK封装层
└── dist/                  # 编译输出

相关链接

• n8n官方文档
• QQ开放平台
• QQ频道机器人开发文档

许可证

MIT

贡献

欢迎提交Issue和Pull Request！

更新日志

0.1.0 (2026-01-17)

• 🎉 初始版本发布
• ✨ 支持发送文本、Markdown、Embed消息
• ✨ 支持接收@消息、频道消息、私信消息触发器