feishu-webhook-sdk

English

轻量、零依赖的 TypeScript SDK，用于通过飞书（Lark）自定义机器人 Webhook 发送消息。支持 Node 18+、Bun、Deno、Cloudflare Workers。支持五种消息类型：text、post、share_chat、image、interactive（卡片消息）。

安装

npm install feishu-webhook-sdk
# 或
pnpm add feishu-webhook-sdk
# 或
bun add feishu-webhook-sdk

快速开始

import { FeishuBot, buildText } from 'feishu-webhook-sdk';

const bot = new FeishuBot(process.env.WEBHOOK!, process.env.SIGN);
await bot.send(buildText('ok'));

说明：

• 若构造时提供了 secret（即 SIGN），SDK 会自动计算签名并在请求体中携带 timestamp 与 sign。
• 请求体最终形如：{ timestamp, sign, msg_type, content }。

发送五种消息

import {
  buildText,
  buildPostZh, text, link, at,
  buildShareChat,
  buildImage,
  buildCard, markdown, button, hr,
} from 'feishu-webhook-sdk';

// 文本
await bot.send(buildText('部署完成 ✅'));

// 富文本（最小：二维数组 + 行内元素）
await bot.send(buildPostZh('发布说明', [
  [ text('版本：v1.2.3') ],
  [ text('变更：'), link('详情', 'https://example.com/changelog'), text(' '), at('ou_xxx') ],
]));

// 群名片（需已知 share_chat_id）
await bot.send(buildShareChat('oc_abcdefg123456'));

// 图片（需已有 image_key）
await bot.send(buildImage('img_ecbefa09-xxxxxx'));

// 卡片消息
await bot.send(buildCard(
  '今日旅游推荐',
  [
    markdown('**西湖**，位于中国浙江省杭州市西湖区'),
    hr(),
    button('🌞 更多景点介绍', 'https://example.com', 'primary'),
  ],
  'blue'
));

多语言富文本消息

import { buildPost, text, link } from 'feishu-webhook-sdk';

// 英文 post
await bot.send(buildPost('en_us', 'Title', [
  [ text('Hello'), link('Link', 'https://example.com') ]
]));

// 中文 post（或使用 buildPostZh 快捷方式）
await bot.send(buildPost('zh_cn', '标题', [
  [ text('你好') ]
]));

卡片消息（Interactive）

重要提示：要使用自定义机器人发送卡片，需满足以下条件：

• 卡片中未添加请求回调交互事件
• 卡片仅用于一次性通知或推广场景，无需再次更新
• 卡片仅向单个指定群组发送

详细说明请查看官方文档。

你可以使用飞书卡片搭建工具来设计和预览卡片。

快速构建卡片

import { buildCard, markdown, div, button, hr } from 'feishu-webhook-sdk';

await bot.send(buildCard(
  '系统通知',
  [
    markdown('**重要提醒**：系统将于今晚 22:00 进行维护'),
    div('预计维护时间：2 小时'),
    hr(),
    button('查看详情', 'https://example.com/maintenance', 'danger'),
  ],
  'red'
));

使用模板方式

import { buildInteractiveTemplate } from 'feishu-webhook-sdk';

// 使用飞书后台创建的卡片模板
await bot.send(buildInteractiveTemplate(
  'AAqyBQVmUNxxx',  // 模板 ID
  { name: '张三', status: '已通过' },  // 模板变量
  '1.0.0'  // 模板版本（可选）
));

自定义 JSON 卡片

import { buildInteractiveCard, markdown, button } from 'feishu-webhook-sdk';

await bot.send(buildInteractiveCard({
  schema: '2.0',
  config: {
    wide_screen_mode: true,
    enable_forward: true,
  },
  header: {
    title: { tag: 'plain_text', content: '自定义卡片' },
    template: 'blue',
  },
  body: {
    elements: [
      markdown('**粗体文本** 和 *斜体文本*'),
      button('点击按钮', 'https://example.com', 'primary'),
    ],
  },
}));

可用的卡片元素

import { markdown, div, button, image, hr } from 'feishu-webhook-sdk';

// Markdown 文本
markdown('**粗体** 和 *斜体*')

// 纯文本或 Lark markdown 文本块
div('纯文本')
div('**Lark markdown**', 'lark_md')

// 按钮（可选 URL 和类型）
button('按钮文本', 'https://example.com', 'primary')  // 'default' | 'primary' | 'danger'

// 图片（需要 image_key）
image('img_xxx', '图片描述')

// 分割线
hr()

直接生成签名并自行发送（可选）

import { generateWebhookSign } from 'feishu-webhook-sdk';

async function sendFeishuMessage(webhook: string, secret: string, textMsg: string) {
  const { timestamp, sign } = await generateWebhookSign(secret);
  const body = { timestamp, sign, msg_type: 'text', content: { text: textMsg } };
  const res = await fetch(webhook, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  try { return await res.json(); } catch { return await res.text(); }
}

运行示例脚本

仓库内提供了一个最小示例（会自动从 .env 读取 WEBHOOK 与 SIGN）：

bun run build
bun run example:send-text

.env 示例：

WEBHOOK=https://open.feishu.cn/xxx
SIGN=your-secret

错误处理

SDK 会在以下情况抛出错误：

• HTTP 错误（非 2xx 状态码）
• 飞书 API 错误（响应中 code !== 0）

try {
  await bot.send(buildText('测试'));
} catch (error) {
  console.error('发送消息失败:', error);
}

设计原则与特性

• 零依赖：使用原生 fetch 与 Web Crypto/Node Crypto。
• 强类型：TypeScript 严格模式，提供最小且清晰的类型定义与 helpers。
• 多运行时：自动选择 WebCrypto 或 Node HMAC 计算签名。
• 简单易用：统一 buildPayload() + bot.send() 思路，同时保留原始 payload 直传。

文档与参考

• 飞书开放平台文档：自定义机器人与消息格式（请在开放平台搜索“自定义机器人 Webhook”“消息结构体 post/text/image/share_chat”）。
• 签名算法：HMAC-SHA256，key 为 ${timestamp}\n${secret}，对空消息签名，结果 Base64。

许可证

MIT