n8n-nodes-feishu-bot

n8n 自定义节点，通过飞书（Feishu/Lark）开放平台 API 操作机器人能力。支持发送/回复/撤回消息、发送图片、管理群组、消息表情反应、接收飞书事件触发工作流。

npm · n8n 社区节点列表

---

安装

在 n8n 中直接安装（推荐）

在 n8n 设置 → Community Nodes，输入：

n8n-nodes-feishu-bot

手动安装到本地 n8n

npm install -g n8n-nodes-feishu-bot

---

前置要求

1. 拥有飞书开发者账号，并创建一个企业自建应用
2. 在应用后台开启以下权限：

权限标识	说明	用途
im:message:send_as_bot	发送消息	发送/回复消息
im:message:receive	接收消息	Webhook 触发
im:message:delete	删除消息	撤回消息
im:message:reply	回复消息	线程内回复
im:message:reaction	消息反应	表情反应
im:chat:readonly	获取群信息	查群详情
im:chat:create	创建群	新建群组
im:chat:manage_members	管理群成员	加bot/删成员
im:chat.update	更新群信息	修改群名/转让群主
im:resource:create	上传媒体资源	发送图片
contact:user.id:readonly	获取用户ID	查询用户

3. 若使用 Webhook Trigger，需在飞书应用后台配置「事件订阅」：
   • 启用 im.message.receive_v1（接收消息）等事件
   • 填入 n8n 分配的 Webhook URL（格式：https://your-n8n.com/webhook/feishu-bot）
   • 若启用了「加密」，需填写 Encrypt Key
4. 将应用发布上线（或创建测试版本）

---

凭证配置

在 n8n 添加凭证

1. n8n 左菜单 → Credentials → New → 搜索 Feishu Bot API
2. 填入以下两个值（从飞书开发者后台获取）：

字段	说明
App ID	飞书应用的 App ID（格式：cli_xxx）
App Secret	飞书应用的 App Secret

3. 点击 Test 验证凭证是否有效

---

节点列表

本包包含两个节点：

节点	说明	触发方式
Feishu Bot	操作类节点，执行发送/管理等动作	手动/自动触发
Feishu Bot Trigger	触发类节点，接收飞书事件触发工作流	被动接收

---

Feishu Bot（操作节点）

1. Send Message — 发送消息

向指定用户或群组发送消息。

参数	类型	说明
Message Type	options	text / post（富文本）/ image / interactive（卡片）
Receive ID Type	options	open_id / user_id / union_id / chat_id / email
Receive ID	string	接收方 ID 值
Message Content	string	消息内容（text 直接填文本；post/card 填 JSON 字符串）

Receive ID Type 示例：

场景	receiveIdType	receiveId 示例
发给指定用户	open_id	ou_xxx
发给群组	chat_id	oc_xxx
发给用户（邮件）	email	user@example.com

---

2. Reply Message — 回复消息

在指定消息的同一线程中回复（支持多楼会话）。

参数	类型	说明
Message ID	string	要回复的消息 ID（msg_id 或 message_id）
Message Type	options	text / post（富文本）/ interactive（卡片）
Reply Content	string	回复内容
Reply In Thread	boolean	true=在原线程中回复；false=普通消息流

---

3. Delete Message — 撤回消息

撤回机器人发送的消息。

参数	类型	说明
Message ID	string	要撤回的消息 ID（机器人只能撤回自己发的消息）

---

4. Send Image — 发送图片

先上传图片获取 image_key，再发送。支持两种图片来源：

图片来源	说明
Binary File	直接从 n8n 输入的二进制文件读取（如 Read File 节点）
Image Key	直接填入已有的 image_key（节省上传配额）

参数	类型	说明
Image Source	options	Binary File / Image Key
Image Binary Property	string	二进制属性名（默认 data），仅 Binary File 模式使用
Image Key	string	直接填入 image_key，仅 Image Key 模式使用
Receive ID Type	options	接收方 ID 类型
Receive ID	string	接收方 ID

---

5. Get User Info — 查询用户信息

参数	类型	说明
User ID Type	options	open_id / user_id / union_id
User ID	string	用户 ID

返回示例：

{
  "user_id": "ou_xxxxx",
  "name": "张三",
  "avatar": { "avatar_72": "https://xxx.com/avatar_72.jpg" },
  "email": "zhangsan@company.com"
}

---

6. Get Group Members — 获取群成员

参数	类型	说明
Chat ID	string	群 ID（oc_xxx）

---

7. Get Group Info — 获取群组信息

参数	类型	说明
Chat ID	string	群 ID（oc_xxx）

返回示例：

{
  "chat_id": "oc_xxx",
  "name": "项目群",
  "description": "项目协作",
  "owner_id": "ou_xxx",
  "owner_id_type": "open_id"
}

---

8. Create Group — 创建群组

参数	类型	说明
Group Name	string	群名称（必填）
Description	string	群描述（可选）

---

9. Update Group — 更新群组信息

参数	类型	说明
Chat ID	string	群 ID（必填）
New Group Name	string	新群名称（可选）
New Description	string	新群描述（可选）
New Owner ID	string	新群主的用户 ID（转让群主时填写）
New Owner ID Type	options	open_id / user_id / union_id

---

10. Delete Group — 删除群组

机器人需为群主才能删除。

参数	类型	说明
Chat ID	string	群 ID（oc_xxx）

---

11. Add Bot to Group — 将机器人加入群组

参数	类型	说明
Chat ID	string	群 ID（oc_xxx）

---

12. Add Reaction — 添加表情反应

参数	类型	说明
Message ID	string	消息 ID
Emoji Type	string	表情类型，如 👍 👎 ❤️ 😄 等

---

13. Remove Reaction — 删除表情反应

参数	类型	说明
Message ID	string	消息 ID
Reaction ID	string	要删除的反应 ID（从 List Reactions 获取）

---

14. List Reactions — 获取消息反应列表

参数	类型	说明
Message ID	string	消息 ID

---

Feishu Bot Trigger（触发节点）

被动接收飞书事件，触发 n8n 工作流运行。

配置步骤

1. 在 n8n 中添加 Feishu Bot Trigger 节点
2. 填写凭证（App ID + App Secret）
3. 填写 Event Type（要订阅的事件类型）
4. 激活工作流，n8n 会分配一个 Webhook URL（格式：https://your-n8n.com/webhook/feishu-bot）
5. 复制该 URL，到飞书开发者后台 → 事件与回调 → 请求地址 URL，填入并保存

Event Type（事件类型）

事件	值	说明
接收消息	im.message.receive_v1	用户发给机器人的消息
消息反应	im.message.reaction	消息被加/删表情反应
群创建	im.chat.create	群组被创建
群解散	im.chat.delete	群组被解散
机器人入群	im.chat.member.bot.join_v1	机器人被加入群组
机器人离群	im.chat.member.bot.leave_v1	机器人被移出群组

Encrypt Key（加密）

若在飞书应用配置中启用了「加密」，填入 Encrypt Key。触发节点会自动解密后再处理。

输出数据格式

以 Receive Messages 为例：

{
  "event_type": "im.message.receive_v1",
  "message_id": "om_xxx",
  "msg_type": "text",
  "content": { "text": "你好" },
  "chat_id": "oc_xxx",
  "root_id": "",
  "parent_id": "",
  "sender": {
    "sender_id": { "open_id": "ou_xxx" },
    "sender_type": "user",
    "tenant_key": "xxx"
  }
}

---

高级用法

多 item 批处理

所有操作节点支持多 item 输入。输入 N 条 item 时，会逐条执行对应操作，输出也按条返回。

AI Agent 中使用

Feishu Bot 节点设置了 usableAsTool: true，可在 n8n AI Agent / Chain 中作为工具调用：

You can use "Feishu Bot" to send messages to Feishu users and groups.

---

错误处理

所有 API 错误统一抛出为 FeishuBotError，包含：

字段	说明
message	错误描述
code	飞书 API 错误码
method	出错的 API 路径

常见错误码：

code	说明
99991401	机器人不在群中
230001	用户不存在
230002	应用没有权限
230015	机器人被禁言

---

架构说明

nodes/FeishuBot/
├── FeishuBot.icon.png          # 节点图标
├── FeishuBot.api.ts            # API 客户端，封装 token 管理和所有飞书 API 调用
├── FeishuBot.node.ts            # 操作节点定义（description + execute）
└── FeishuBot.trigger.ts        # 触发节点定义（webhook 方法）

credentials/
└── FeishuBotApi.credentials.ts # 凭证类型（appId + appSecret）

设计原则：

• FeishuBot.api.ts — 纯业务逻辑，不引用 n8n，通过 @larksuiteoapi/node-sdk 调飞书 API
• FeishuBot.node.ts — 参数映射和 execute 编排
• Token 自动刷新，API 返回 code !== 0 时自动重试一次（处理 token 过期场景）

---

开发

# 安装依赖
npm install

# 构建（TypeScript → dist/）
npm run build

# 开发监听模式
npm run dev

# 测试
npm test

# 发布（修改 version 后执行）
npm publish --access public --registry https://registry.npmjs.org --ignore-scripts

---

更新日志

版本	内容
0.0.7	新增：Reply Message、Delete Message、Send Image、Get/Update Group、Add/Remove/List Reactions；新增 Feishu Bot Trigger 节点，支持接收飞书事件触发工作流
0.0.6	修复 README 未显示问题
0.0.5	新增自定义图标
0.0.3	改用原生 @larksuiteoapi/node-sdk（回退 axios 方案）
0.0.1	初始版本：Send Message、Get User Info、Get Group Members、Create/Delete Group、Add Bot to Group

---

License

MIT