飞书消息推送 API 参考文档

概述

本模块提供两种消息推送方式：

Webhook 方式：推送到群组，无需 access token
开放平台 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 不同而不同

请求示例：

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: '这是一条测试消息' }
  })
});

响应示例：

{
  "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	是	消息文本内容

请求示例：

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	是	消息内容数组（二维数组）

请求示例（@单个用户）：

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: ' 您有一个新任务需要处理' }
      ]
    ]
  })
});

请求示例（@所有人）：

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。

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（发送到群组）

请求示例（发送文本消息）：

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: '您好，这是一条测试消息' }
  })
});

请求示例（发送富文本消息）：

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' }
          ]
        ]
      }
    }
  })
});

响应示例：

{
  "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	是	消息文本内容

请求示例：

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	是	消息内容

请求示例：

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 分钟后开始，请准时参加' }
  })
});

响应示例：

{
  "success": true,
  "data": {
    "message": "批量发送完成: 成功 3 条，失败 0 条",
    "success_count": 3,
    "failed_count": 0,
    "failed_details": []
  },
  "timestamp": "2026-03-09T14:00:00.000Z"
}

错误处理

错误响应格式

{
  "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：系统告警（推送到群组）

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：任务分配（推送到个人）

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：批量通知（推送到多人）

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 分钟后开始，请准时参加'
);

API_REFERENCE.md 12 KB

文件歷史 原始文件

飞书消息推送 API 参考文档

概述

基础 URL

接口分类

一、Webhook 方式（推送到群组）

1.1 通用消息发送

1.2 发送文本消息

1.3 发送富文本消息

二、开放平台 API 方式（推送到个人）

2.1 发送消息到个人

2.2 发送文本消息到个人（简化版）

2.3 批量发送消息到多人

错误处理

错误响应格式

常见错误

Webhook 方式错误

开放平台 API 错误

使用场景对比

何时使用 Webhook 方式？

何时使用开放平台 API？

完整示例

示例 1：系统告警（推送到群组）

示例 2：任务分配（推送到个人）

示例 3：批量通知（推送到多人）

参考资料

API_REFERENCE.md 12 KB 文件歷史 原始文件

飞书消息推送 API 参考文档

概述

基础 URL

接口分类

一、Webhook 方式（推送到群组）

1.1 通用消息发送

1.2 发送文本消息

1.3 发送富文本消息

二、开放平台 API 方式（推送到个人）

2.1 发送消息到个人

2.2 发送文本消息到个人（简化版）

2.3 批量发送消息到多人

错误处理

错误响应格式

常见错误

Webhook 方式错误

开放平台 API 错误

使用场景对比

何时使用 Webhook 方式？

何时使用开放平台 API？

完整示例

示例 1：系统告警（推送到群组）

示例 2：任务分配（推送到个人）

示例 3：批量通知（推送到多人）

参考资料

API_REFERENCE.md 12 KB

文件歷史原始文件