Lark Suite Node.js SDK

The SDK provides an EventDispatcher to handle incoming events from the Feishu platform. It manages event registration, data decryption, and integration with web servers.

Workflow

1. Create an instance of EventDispatcher.
2. Register event listeners using .register({ 'event.key': handler }).
3. Bind the instance to your server using an adapter (e.g., adaptDefault, adaptExpress, adaptKoa).

EventDispatcher Configuration

Unregistering Events

Use .unregister(...keys) to remove handlers for specific event keys. This supports chaining.

const eventDispatcher = new lark.EventDispatcher({}).register({
    'im.message.receive_v1': async (data) => {},
});

eventDispatcher
    .unregister('im.message.receive_v1')
    .register({
        'im.message.receive_v1': async (data) => {},
    });

const eventDispatcher = new lark.EventDispatcher({
    encryptKey: 'encrypt key'
}).register({
    'im.message.receive_v1': async (data) => {
        const chatId = data.message.chat_id;
        const res = await client.im.message.create({
            params: {
                receive_id_type: 'chat_id',
            },
            data: {
                receive_id: chatId,
                content: JSON.stringify({text: 'hello world'}),
                msg_type: 'text'
            },
        });
        return res;
    }
});

The Channel module is a high-level abstraction built on top of WSClient, EventDispatcher, and Client. It is designed for building conversational bots that require features like message normalization, security policies, outbound sending, streaming replies, media uploads, and card interactions.

When to use Channel:

• Building AI chat bots.
• Implementing streaming replies (typewriter effect).
• Handling card button interactions.
• Managing media uploads and @all strategies.

When to use lower-level components:

• If you only need to process a small number of events with simple logic, the WSClient + EventDispatcher combination is sufficient.

import { createLarkChannel, LoggerLevel } from '@larksuiteoapi/node-sdk';

const channel = createLarkChannel({
    appId: process.env.FEISHU_APP_ID!,
    appSecret: process.env.FEISHU_APP_SECRET!,
    loggerLevel: LoggerLevel.info,
    policy: { requireMention: true, dmMode: 'open' },
});

channel.on('message', async (msg) => {
    await channel.send(
        msg.chatId,
        { markdown: `收到：${msg.content}` },
        { replyTo: msg.messageId },
    );
});

await channel.connect();
console.log(`connected as ${channel.botIdentity!.name}`);

process.on('SIGINT', async () => {
    await channel.disconnect();
    process.exit(0);
});

To create a basic bot that responds to messages, use createLarkChannel, call connect(), and listen for the message event. The connect() method resolves once the WebSocket handshake is complete, at which point channel.botIdentity becomes available.

import { createLarkChannel, LoggerLevel } from '@larksuiteoapi/node-sdk';

const channel = createLarkChannel({
    appId: process.env.FEISHU_APP_ID!,
    appSecret: process.env.FEISHU_APP_SECRET!,
    loggerLevel: LoggerLevel.info,
    policy: { requireMention: true, dmMode: 'open' },
});

channel.on('message', async (msg) => {
    await channel.send(
        msg.chatId,
        { markdown: `received: ${msg.content}` },
        { replyTo: msg.messageId },
    );
});

await channel.connect();
console.log(`connected as ${channel.botIdentity!.name}`);

process.on('SIGINT', async () => {
    await channel.disconnect();
    process.exit(0);
});

To process events (like receiving a message), use the EventDispatcher. It handles data decryption internally if an encryptKey is provided.

Workflow:

1. Create an EventDispatcher instance.
2. Register event keys and their handler functions using .register().
3. Use an adapter (like adaptExpress, adaptKoa, or adaptDefault) to bind the dispatcher to your web server.

Challenge Verification: When configuring a webhook, the platform sends a challenge field to verify the URL. Use the autoChallenge: true option in your adapter to handle this automatically.

import http from 'http';
import * as lark from '@larksuiteoapi/node-sdk';

const eventDispatcher = new lark.EventDispatcher({
    encryptKey: 'encrypt key'
}).register({
    'im.message.receive_v1': async (data) => {
        const chatId = data.message.chat_id;
        // Handle event logic here
    }
});

const server = http.createServer();
// Use autoChallenge: true to handle URL verification
server.on('request', lark.adaptDefault('/webhook/event', eventDispatcher, {
    autoChallenge: true,
}));
server.listen(3000);

The registerApp method allows for one-click app creation using the OAuth 2.0 Device Authorization Grant protocol. It generates a verification URL for users to scan, which then automatically registers the app and returns credentials.

Customizing Scopes and Events (Addons)

You can use the addons parameter to incrementally request specific permissions (scopes, events, or callbacks) during the registration process.

• addons.preset:
  • true (default): Keeps the platform's default template and adds your requested items on top.
  • false: Drops the default template and starts from a minimal base (bot capability only), showing only your declared items.
• addons is additive only: You cannot use it to remove base permissions.

import * as lark from '@larksuiteoapi/node-sdk';

try {
    const result = await lark.registerApp({
        addons: {
            preset: false,
            scopes: { tenant: ['im:message:send_as_bot'] },
            events: { items: { tenant: ['im.message.receive_v1'] } },
        },
        onQRCodeReady(info) {
            console.log(`Scan the QR code: ${info.url}`);
        },
    });

    console.log('App ID:', result.client_id);
    console.log('App Secret:', result.client_secret);
} catch (e) {
    console.error(e.code, e.description);
}