| 订阅方式 | 介绍 |
|---|---|
| 使用长连接接收回调 | 该方式是飞书 SDK 内提供的能力,你可以通过集成飞书 SDK 与开放平台建立一条 WebSocket 全双工通道(你的服务器需要能够访问公网)。后续当应用订阅的回调发生时,开放平台会通过该通道向你的服务器发送消息。相较于传统的 Webhook 模式,长连接模式大大降低了接入成本,将原先 1 周左右的开发周期降低到 5 分钟。具体优势如下:测试阶段无需使用内网穿透工具,通过长连接模式在本地开发环境中即可接收回调。SDK 内封装了鉴权逻辑,只在建连时进行鉴权,后续回调推送均为明文数据,无需再处理解密和验签逻辑。只需保证运行环境具备访问公网能力即可,无需提供公网 IP 或域名。无需部署防火墙和配置白名单。 |
| 将回调发送至开发者服务器 | 传统的 Webhook 模式,该方式需要你提供用于接收回调消息的服务器公网地址。后续当应用订阅的回调发生时,开放平台会向服务器的公网地址发送 HTTP POST 请求,请求内包含回调数据。 |

{
"behaviors": [
{ // 声明交互类型是卡片回传交互。
"type": "callback",
"value": {
// 回传交互数据。开放平台 SDK 仅支持对象类型的卡片回传参数。
"key": "value"
}
}
]
}import * as Lark from "@larksuiteoapi/node-sdk";
const wsClient = new Lark.WSClient({
appId: "YOUR_APP_ID",
appSecret: "YOUR_APP_SECRET",
});
const eventDispatcher = new Lark.EventDispatcher({}).register({
"card.action.trigger": async (data) => {
console.log(data);
return {
toast: {
type: "success",
content: "卡片交互成功",
i18n: {
zh_cn: "卡片交互成功",
en_us: "card action success",
},
},
};
},
});
wsClient.start({ eventDispatcher });
new Lark.EventDispatcher 初始化事件处理器(eventDispatcher)。[info]: [ "[ws]", "ws client ready" ],主线程将阻塞,直到进程结束。
EventDispatcher 的实例。EventDispatcher 内部会进行数据解密等操作,构造参数说明如下表所示。如果没有传递相关参数,则会自动忽略对应的参数配置。| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| encryptKey | string | 否 | 推送数据加密的 key,开启加密推送时需要使用该参数进行数据解密。关于 encryptKey 的更多信息,参见配置 Encrypt Key。 |
| loggerLevel | LoggerLevel | 否 | 日志级别。枚举值:lark.LoggerLevel.error:记录错误事件,这些事件阻止了部分程序的执行。lark.LoggerLevel.warn:记录异常问题,但这些异常可能不影响程序继续运行。lark.LoggerLevel.info:记录运行过程中关键的、需要被监控的信息。lark.LoggerLevel.debug:记录调试信息,用于在调试时诊断问题。lark.LoggerLevel.trace:记录详细信息,可用于开发或调试时跟踪程序运行过程。默认值:lark.LoggerLevel.info |
| logger | Logger | 否 | 日志器,可根据需要自定义配置。 |
| cache | Cache | 否 | 缓存器,用于缓存数据的存储与获取,如 token 。如果你没有指定缓存器,SDK 会初始化一个缓存器。如果需要和现有系统共享数据,可以自定义缓存器,实现 Cache 的接口即可。默认缓存器的实现:default-cache.ts |
'card.action.trigger'位置对应传入回调的 回调类型,如卡片回传交互回调类型为 card.action.trigger,拉取链接预览数据回调类型为 url.preview.get。import http from 'http';
import * as lark from '@larksuiteoapi/node-sdk';
const eventDispatcher = new lark.EventDispatcher({
encryptKey: 'encrypt key'
}).register({
'card.action.trigger': async (data) => {
console.log(data);
return {
toast: {
type: "success",
content: "卡片交互成功",
i18n: {
zh_cn: "卡片交互成功",
en_us: "card action success",
},
},
};
},
});
const server = http.createServer();
server.on('request', lark.adaptDefault('/webhook/event', eventDispatcher, {
autoChallenge:true,
}));
server.listen(3000);