# 飞书消息推送 API 参考文档 ## 概述 本模块提供两种消息推送方式： 1. **Webhook 方式**：推送到群组，无需 access token 2. **开放平台 API 方式**：推送到个人聊天，需要 access token ## 基础 URL ``` http://your-server:3000/api/feishu ``` ## 接口分类 ### 一、Webhook 方式（推送到群组） 这些接口使用飞书自定义机器人的 Webhook URL，无需配置 access token。 #### 1.1 通用消息发送 **接口地址：** `POST /send` **功能说明：** 支持发送所有类型的飞书消息到群组。 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | webhook_url | string | 是 | 飞书机器人的 Webhook URL | | msg_type | string | 是 | 消息类型：text、post、interactive | | content | object | 是 | 消息内容，根据 msg_type 不同而不同 | **请求示例：** ```javascript fetch('http://your-server:3000/api/feishu/send', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ webhook_url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx', msg_type: 'text', content: { text: '这是一条测试消息' } }) }); ``` **响应示例：** ```json { "success": true, "data": { "message": "消息发送成功", "feishu_response": { "code": 0, "msg": "success" } }, "timestamp": "2026-03-09T14:00:00.000Z" } ``` #### 1.2 发送文本消息 **接口地址：** `POST /send/text` **功能说明：** 快速发送纯文本消息到群组。 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | webhook_url | string | 是 | 飞书机器人的 Webhook URL | | text | string | 是 | 消息文本内容 | **请求示例：** ```javascript fetch('http://your-server:3000/api/feishu/send/text', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ webhook_url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx', text: '这是一条简单的文本消息' }) }); ``` #### 1.3 发送富文本消息 **接口地址：** `POST /send/post` **功能说明：** 发送富文本消息到群组，支持标题、@用户、链接等。 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | webhook_url | string | 是 | 飞书机器人的 Webhook URL | | title | string | 否 | 消息标题 | | content | array | 是 | 消息内容数组（二维数组） | **请求示例（@单个用户）：** ```javascript fetch('http://your-server:3000/api/feishu/send/post', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ webhook_url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx', title: '任务提醒', content: [ [ { tag: 'at', user_id: 'ou_xxxxxx' }, { tag: 'text', text: ' 您有一个新任务需要处理' } ] ] }) }); ``` **请求示例（@所有人）：** ```javascript fetch('http://your-server:3000/api/feishu/send/post', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ webhook_url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx', title: '重要通知', content: [ [ { tag: 'at', user_id: 'all' }, { tag: 'text', text: ' 系统将于今晚 22:00 进行维护' } ] ] }) }); ``` ### 二、开放平台 API 方式（推送到个人） 这些接口使用飞书开放平台 API，需要配置 access token。详见 [ACCESS_TOKEN.md](./ACCESS_TOKEN.md)。 #### 2.1 发送消息到个人 **接口地址：** `POST /message/send` **功能说明：** 直接发送消息到个人聊天。 **前置条件：** - 已配置 FEISHU_APP_ID 和 FEISHU_APP_SECRET 环境变量 - 应用已开通 im:message 权限 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | receive_id_type | string | 是 | 接收者 ID 类型：open_id、user_id、union_id、email、chat_id | | receive_id | string | 是 | 接收者 ID | | msg_type | string | 是 | 消息类型：text、post、interactive | | content | object/string | 是 | 消息内容 | **receive_id_type 说明：** - `open_id`: 用户的 Open ID（推荐，最常用） - `user_id`: 用户的 User ID（企业内部 ID） - `union_id`: 用户的 Union ID（跨应用唯一） - `email`: 用户的邮箱地址 - `chat_id`: 群组 ID（发送到群组） **请求示例（发送文本消息）：** ```javascript fetch('http://your-server:3000/api/feishu/message/send', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_id: 'ou_xxxxxx', msg_type: 'text', content: { text: '您好，这是一条测试消息' } }) }); ``` **请求示例（发送富文本消息）：** ```javascript fetch('http://your-server:3000/api/feishu/message/send', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_id: 'ou_xxxxxx', msg_type: 'post', content: { zh_cn: { title: '任务提醒', content: [ [ { tag: 'text', text: '您有一个新任务：' }, { tag: 'a', text: '点击查看', href: 'https://example.com/task/123' } ] ] } } }) }); ``` **响应示例：** ```json { "success": true, "data": { "message": "消息发送成功", "feishu_response": { "code": 0, "msg": "success", "data": { "message_id": "om_xxx" } } }, "timestamp": "2026-03-09T14:00:00.000Z" } ``` #### 2.2 发送文本消息到个人（简化版） **接口地址：** `POST /message/send/text` **功能说明：** 快速发送纯文本消息到个人聊天。 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | receive_id_type | string | 是 | 接收者 ID 类型 | | receive_id | string | 是 | 接收者 ID | | text | string | 是 | 消息文本内容 | **请求示例：** ```javascript fetch('http://your-server:3000/api/feishu/message/send/text', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_id: 'ou_xxxxxx', text: '您好，这是一条测试消息' }) }); ``` #### 2.3 批量发送消息到多人 **接口地址：** `POST /message/send/batch` **功能说明：** 批量发送相同消息到多个用户。 **请求参数：** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | receive_id_type | string | 是 | 接收者 ID 类型 | | receive_ids | array | 是 | 接收者 ID 数组 | | msg_type | string | 是 | 消息类型 | | content | object/string | 是 | 消息内容 | **请求示例：** ```javascript fetch('http://your-server:3000/api/feishu/message/send/batch', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_ids: ['ou_user1', 'ou_user2', 'ou_user3'], msg_type: 'text', content: { text: '会议将于 10 分钟后开始，请准时参加' } }) }); ``` **响应示例：** ```json { "success": true, "data": { "message": "批量发送完成: 成功 3 条，失败 0 条", "success_count": 3, "failed_count": 0, "failed_details": [] }, "timestamp": "2026-03-09T14:00:00.000Z" } ``` ## 错误处理 ### 错误响应格式 ```json { "success": false, "error": "错误信息", "timestamp": "2026-03-09T14:00:00.000Z" } ``` ### 常见错误 #### Webhook 方式错误 | HTTP 状态码 | 错误信息 | 说明 | 解决方法 | |------------|---------|------|---------| | 400 | webhook_url 是必填项 | 未提供 webhook_url | 检查请求参数 | | 400 | webhook_url 格式不正确 | URL 格式错误 | 确认 URL 以 https://open.feishu.cn/open-apis/bot/v2/hook/ 开头 | | 500 | 飞书消息发送失败 | 飞书 API 返回错误 | 检查 Webhook URL 是否有效 | #### 开放平台 API 错误 | HTTP 状态码 | 错误信息 | 说明 | 解决方法 | |------------|---------|------|---------| | 400 | receive_id_type 是必填项 | 未提供接收者类型 | 检查请求参数 | | 400 | receive_id 是必填项 | 未提供接收者 ID | 检查请求参数 | | 500 | 飞书配置无效 | 未配置环境变量 | 配置 FEISHU_APP_ID 和 FEISHU_APP_SECRET | | 500 | 获取飞书 token 失败 | Token 获取失败 | 检查 app_id 和 app_secret 是否正确 | | 500 | 飞书消息发送失败 | API 调用失败 | 检查应用权限和接收者 ID | ## 使用场景对比 ### 何时使用 Webhook 方式？ **适用场景：** - 推送到群组 - 不需要推送到个人聊天 - 简单快速，无需额外配置 **优点：** - 配置简单，只需 Webhook URL - 无需管理 access token - 适合快速集成 **缺点：** - 只能推送到群组 - 无法推送到个人聊天 ### 何时使用开放平台 API？ **适用场景：** - 需要推送到个人聊天 - 需要批量推送到多人 - 需要更精细的权限控制 **优点：** - 可以推送到个人聊天 - 支持批量推送 - 功能更强大 **缺点：** - 需要配置 app_id 和 app_secret - 需要管理 access token - 需要开通应用权限 ## 完整示例 ### 示例 1：系统告警（推送到群组） ```javascript async function sendAlert(message) { const response = await fetch('http://your-server:3000/api/feishu/send/post', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ webhook_url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx', title: '⚠️ 系统告警', content: [ [ { tag: 'at', user_id: 'all' }, { tag: 'text', text: ' 系统检测到异常' } ], [ { tag: 'text', text: `错误信息：${message}` } ] ] }) }); return response.json(); } ``` ### 示例 2：任务分配（推送到个人） ```javascript async function assignTask(userId, taskName, taskUrl) { const response = await fetch('http://your-server:3000/api/feishu/message/send', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_id: userId, msg_type: 'post', content: { zh_cn: { title: '📋 新任务分配', content: [ [ { tag: 'text', text: `您有一个新任务：${taskName}` } ], [ { tag: 'text', text: '查看详情：' }, { tag: 'a', text: '点击这里', href: taskUrl } ] ] } } }) }); return response.json(); } ``` ### 示例 3：批量通知（推送到多人） ```javascript async function notifyMultipleUsers(userIds, message) { const response = await fetch('http://your-server:3000/api/feishu/message/send/batch', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ receive_id_type: 'open_id', receive_ids: userIds, msg_type: 'text', content: { text: message } }) }); return response.json(); } // 使用示例 notifyMultipleUsers( ['ou_user1', 'ou_user2', 'ou_user3'], '会议将于 10 分钟后开始，请准时参加' ); ``` ## 参考资料 - [飞书开放平台 - 自定义机器人](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot) - [飞书开放平台 - 发送消息](https://open.feishu.cn/document/server-docs/im-v1/message/create) - [ACCESS_TOKEN.md - Access Token 配置指南](./ACCESS_TOKEN.md)