飞书机器人长链接接收回调示例

这是一个使用飞书官方 Node.js SDK 实现长链接接收事件回调的完整示例项目。

✨ 特性

• 🔗 长链接模式: 无需配置公网域名和回调地址
• 🛡️ 安全加密: 内置通信加密和鉴权逻辑
• 🎯 事件处理: 支持多种消息类型和事件回调
• 📝 示例丰富: 包含文本消息、命令处理、卡片消息等示例
• 🏗️ 架构清晰: 代码模块化，易于扩展和维护

🚀 快速开始

1. 环境准备

确保你的开发环境满足以下要求：

• Node.js 14.0 或更高版本
• npm 或 yarn 包管理器
• 能够访问公网（长链接需要）

2. 飞书应用配置

在使用之前，你需要在飞书开发者后台创建应用并获取必要的配置信息：

1. 访问 飞书开发者后台
2. 创建企业自建应用
3. 获取以下配置信息：
   • App ID (应用 ID)
   • App Secret (应用密钥)
   • Verification Token (验证令牌，可选)
   • Encrypt Key (加密密钥，可选)

3. 项目配置

1. 克隆或下载项目

   git clone https://github.com/haotian2546/feishu-persistent-connection-demo.git
   cd feishu-persistent-connection-demo

2. 安装依赖

   npm install

3. 配置环境变量

   复制 .env 文件并填入你的应用配置信息：

   cp .env .env.local

   编辑 .env.local 文件：

   # 飞书应用配置信息
   FEISHU_APP_ID=cli_xxxxxxxxx          # 替换为你的 App ID
   FEISHU_APP_SECRET=xxxxxxxxx           # 替换为你的 App Secret
   FEISHU_VERIFICATION_TOKEN=xxxxxxxxx   # 替换为你的 Verification Token (可选)
   FEISHU_ENCRYPT_KEY=xxxxxxxxx          # 替换为你的 Encrypt Key (可选)
   
   # 环境配置
   NODE_ENV=development
   PORT=3000
   LOG_LEVEL=info

4. 启动服务

# 开发模式
npm run dev

# 生产模式
npm start

启动成功后，你会看到类似以下的输出：

🚀 正在启动飞书长链接服务...
📋 应用配置:
  - App ID: cli_xxxxxxxxx
  - 环境: development
  - 日志级别: info
✅ 长链接已建立，开始接收事件回调
🎉 飞书长链接服务启动成功！
💡 提示: 现在可以在飞书中向机器人发送消息进行测试

5. 测试功能

在飞书中找到你的机器人，发送以下命令进行测试：

• /help - 显示帮助信息
• /ping - 测试连接
• /info - 显示机器人信息
• 发送普通文本消息 - 机器人会回复相同内容

📁 项目结构

feishuapi/
├── src/
│   ├── longConnection.js    # 长链接服务核心文件
│   └── eventHandlers.js     # 事件处理器示例
├── index.js                 # 主入口文件
├── package.json            # 项目配置
├── .env                    # 环境变量模板
├── .gitignore             # Git 忽略文件
└── README.md              # 项目说明

🛠️ 核心功能

长链接服务 (src/longConnection.js)

• 配置飞书客户端
• 创建事件分发器
• 注册各种事件回调
• 启动和管理 WebSocket 连接

事件处理器 (src/eventHandlers.js)

• 文本消息处理
• 命令解析和执行
• 图片和文件消息处理
• 消息回复功能
• 富文本和卡片消息支持

📝 支持的事件类型

当前示例支持以下事件类型：

• im.message.receive_v1 - 接收消息事件
• application.bot.menu_v6 - 机器人菜单事件
• im.chat.member.bot.added_v1 - 机器人被添加到群聊
• im.chat.member.bot.deleted_v1 - 机器人被移出群聊

你可以根据需要在 eventDispatcher.register() 中添加更多事件类型。

🔧 自定义开发

添加新的命令

在 src/eventHandlers.js 的 handleCommand 函数中添加新的命令处理逻辑：

case '/mycmd':
  return await replyMessage(messageId, '这是我的自定义命令');

添加新的事件类型

在 src/longConnection.js 的 eventDispatcher.register() 中添加新的事件处理器：

'your.event.type_v1': async (data) => {
  console.log('收到自定义事件:', data);
  // 处理逻辑
  return { code: 0 };
},

发送不同类型的消息

使用 eventHandlers.js 中提供的函数：

// 发送文本消息
await replyMessage(messageId, '文本内容');

// 发送富文本消息
await replyRichTextMessage(messageId, richContent);

// 发送卡片消息
const card = createSimpleCard('标题', '内容');
await replyCardMessage(messageId, card);

🐛 常见问题

1. 长链接无法建立

• 检查网络连接是否正常
• 确认 App ID 和 App Secret 是否正确
• 检查防火墙设置

2. 收不到事件回调

• 确认应用已正确配置事件权限
• 检查 Verification Token 是否正确
• 确保机器人已被正确添加到会话中

3. 消息发送失败

• 检查机器人是否有发送消息权限
• 确认会话 ID 和用户 ID 是否正确
• 查看控制台错误日志

📚 相关文档

• 飞书开放平台
• 飞书 Node.js SDK GitHub
• 飞书机器人开发指南
• 长链接事件回调文档

📄 许可证

ISC License

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！