hongben-server/api/module/feishu/docs

飞书机器人推送接口文档

概述

本模块提供了飞书机器人消息推送功能，支持向飞书群组或个人发送消息。通过简单的 HTTP 接口调用，前端可以轻松实现飞书消息推送。

前置准备

1. 创建飞书机器人

在使用接口之前，需要先在飞书群组中创建自定义机器人：

1. 打开飞书群组
2. 点击群设置 → 群机器人 → 添加机器人
3. 选择"自定义机器人"
4. 配置机器人名称、描述等信息
5. 获取 Webhook URL（格式：https://open.feishu.cn/open-apis/bot/v2/hook/xxx）

重要提示：

• 每个群组可以创建多个机器人
• Webhook URL 包含机器人的访问凭证，请妥善保管
• 机器人发送的消息会显示机器人的名称和头像

2. 配置安全设置（可选）

飞书机器人支持以下安全设置：

• 签名验证：通过签名验证请求来源
• IP 白名单：限制只有特定 IP 可以调用
• 关键词验证：消息必须包含特定关键词

本接口暂不支持签名验证，如需使用请在飞书后台配置 IP 白名单或关键词验证。

接口列表

基础 URL

http://your-server:3000/api/feishu

1. 通用消息发送接口

接口地址： POST /api/feishu/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: '这是一条测试消息'
    }
  })
})
.then(res => res.json())
.then(data => console.log(data));

响应示例：

{
  "success": true,
  "data": {
    "message": "消息发送成功",
    "feishu_response": {
      "code": 0,
      "msg": "success"
    }
  },
  "timestamp": "2026-03-09T11:45:00.000Z"
}

2. 文本消息发送接口（简化版）

接口地址： POST /api/feishu/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: '这是一条简单的文本消息'
  })
})
.then(res => res.json())
.then(data => console.log(data));

响应示例：

{
  "success": true,
  "data": {
    "message": "文本消息发送成功",
    "feishu_response": {
      "code": 0,
      "msg": "success"
    }
  },
  "timestamp": "2026-03-09T11:45:00.000Z"
}

3. 富文本消息发送接口（支持 @用户）

接口地址： POST /api/feishu/send/post

功能说明： 发送富文本消息，支持标题、多段落、@用户、链接等丰富格式。

请求参数：

参数名	类型	必填	说明
webhook_url	string	是	飞书机器人的 Webhook URL
title	string	否	消息标题
content	array	是	消息内容数组，详见下方说明

content 格式说明：

content 是一个二维数组，第一层代表段落，第二层代表段落内的元素。

支持的元素类型：

• text：普通文本
• a：链接
• at：@用户

请求示例 1：发送带标题的富文本消息

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: 'text', text: '您有一条新的任务待处理' }
      ],
      [
        { tag: 'text', text: '任务详情：' },
        { tag: 'a', text: '点击查看', href: 'https://example.com/task/123' }
      ]
    ]
  })
})
.then(res => res.json())
.then(data => console.log(data));

请求示例 2：@单个用户

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: ' 您有一个新任务需要处理' }
      ]
    ]
  })
})
.then(res => res.json())
.then(data => console.log(data));

请求示例 3：@所有人

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 进行维护，请提前保存工作' }
      ]
    ]
  })
})
.then(res => res.json())
.then(data => console.log(data));

请求示例 4：@多个用户

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_user1' },
        { tag: 'text', text: ' ' },
        { tag: 'at', user_id: 'ou_user2' },
        { tag: 'text', text: ' 请查看最新的项目进度' }
      ],
      [
        { tag: 'text', text: '详情：' },
        { tag: 'a', text: '项目看板', href: 'https://example.com/project' }
      ]
    ]
  })
})
.then(res => res.json())
.then(data => console.log(data));

响应示例：

{
  "success": true,
  "data": {
    "message": "富文本消息发送成功",
    "feishu_response": {
      "code": 0,
      "msg": "success"
    }
  },
  "timestamp": "2026-03-09T11:45:00.000Z"
}

错误处理

错误响应格式

{
  "success": false,
  "error": "错误信息",
  "timestamp": "2026-03-09T11:45:00.000Z"
}

常见错误码

HTTP 状态码	错误信息	说明
400	webhook_url 是必填项	未提供 webhook_url
400	msg_type 是必填项	未提供 msg_type
400	content 是必填项	未提供 content
400	webhook_url 格式不正确	webhook_url 不是有效的飞书 Webhook URL
500	飞书消息发送失败	飞书 API 返回错误
500	消息发送失败	网络错误或其他异常

使用场景示例

场景 1：系统告警通知

// 当系统检测到异常时，发送告警消息
async function sendAlert(errorMessage) {
  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: `错误信息：${errorMessage}` }
        ],
        [
          { tag: 'text', text: `时间：${new Date().toLocaleString()}` }
        ]
      ]
    })
  });
  return response.json();
}

场景 2：任务分配通知

// 当任务分配给用户时，发送通知
async function notifyTaskAssignment(userId, taskName, taskUrl) {
  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: userId },
          { tag: 'text', text: ` 您有一个新任务：${taskName}` }
        ],
        [
          { tag: 'text', text: '查看详情：' },
          { tag: 'a', text: '点击这里', href: taskUrl }
        ]
      ]
    })
  });
  return response.json();
}

场景 3：批量通知

// 向多个用户发送通知
async function notifyMultipleUsers(userIds, message) {
  // 构建 @用户 的内容
  const atUsers = userIds.flatMap(userId => [
    { tag: 'at', user_id: userId },
    { tag: 'text', text: ' ' }
  ]);

  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: [
        atUsers,
        [
          { tag: 'text', text: message }
        ]
      ]
    })
  });
  return response.json();
}

// 使用示例
notifyMultipleUsers(
  ['ou_user1', 'ou_user2', 'ou_user3'],
  '会议将于 10 分钟后开始，请准时参加'
);

注意事项

1. Webhook URL 安全

   • Webhook URL 包含访问凭证，请勿在前端代码中硬编码
   • 建议将 Webhook URL 存储在后端配置或数据库中
   • 可以为不同的群组或场景配置不同的机器人

2. 消息频率限制

   • 飞书机器人有消息发送频率限制（通常为 20 条/分钟）
   • 超过限制会返回错误，请合理控制发送频率
   • 建议实现消息队列机制，避免短时间内大量发送

3. 用户 ID 获取

   • @用户需要提供用户的 Open ID（格式：ou_xxxxxx）
   • 可以通过飞书开放平台 API 获取用户 ID
   • @所有人使用 user_id: 'all'

4. 消息格式

   • 富文本消息的 content 必须是二维数组
   • 每个段落是一个数组，包含多个元素
   • 元素必须包含 tag 字段，根据不同 tag 提供对应的字段

5. 错误处理

   • 建议在前端实现重试机制
   • 记录发送失败的消息，便于排查问题
   • 对用户友好地展示错误信息

完整的前端封装示例

// feishu-bot.js
class FeishuBot {
  constructor(baseUrl = 'http://your-server:3000/api/feishu') {
    this.baseUrl = baseUrl;
  }

  /**
   * 发送文本消息
   */
  async sendText(webhookUrl, text) {
    return this._request('/send/text', {
      webhook_url: webhookUrl,
      text
    });
  }

  /**
   * 发送富文本消息
   */
  async sendPost(webhookUrl, title, content) {
    return this._request('/send/post', {
      webhook_url: webhookUrl,
      title,
      content
    });
  }

  /**
   * @单个用户
   */
  async mentionUser(webhookUrl, userId, message, title = '通知') {
    return this.sendPost(webhookUrl, title, [
      [
        { tag: 'at', user_id: userId },
        { tag: 'text', text: ` ${message}` }
      ]
    ]);
  }

  /**
   * @所有人
   */
  async mentionAll(webhookUrl, message, title = '重要通知') {
    return this.sendPost(webhookUrl, title, [
      [
        { tag: 'at', user_id: 'all' },
        { tag: 'text', text: ` ${message}` }
      ]
    ]);
  }

  /**
   * @多个用户
   */
  async mentionMultiple(webhookUrl, userIds, message, title = '通知') {
    const atUsers = userIds.flatMap(userId => [
      { tag: 'at', user_id: userId },
      { tag: 'text', text: ' ' }
    ]);

    return this.sendPost(webhookUrl, title, [
      atUsers,
      [{ tag: 'text', text: message }]
    ]);
  }

  /**
   * 内部请求方法
   */
  async _request(endpoint, data) {
    try {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data)
      });

      const result = await response.json();

      if (!result.success) {
        throw new Error(result.error || '发送失败');
      }

      return result;
    } catch (error) {
      console.error('飞书消息发送失败:', error);
      throw error;
    }
  }
}

// 使用示例
const bot = new FeishuBot();

// 发送文本消息
bot.sendText(
  'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  '这是一条测试消息'
);

// @单个用户
bot.mentionUser(
  'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  'ou_xxxxxx',
  '您有新的任务'
);

// @所有人
bot.mentionAll(
  'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  '系统维护通知'
);

// @多个用户
bot.mentionMultiple(
  'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  ['ou_user1', 'ou_user2'],
  '会议即将开始'
);

参考资料

• 飞书开放平台 - 自定义机器人指南
• 飞书开放平台 - 消息类型说明

更新日志

• 2026-03-09：初始版本，支持文本消息和富文本消息发送