Lark / Feishu Channel

Lark channels connect one Feishu or Lark custom app to one Netmind Cloud Agent. NCA can receive messages by webhook or by Lark WebSocket subscription.

Webhook mode is the Admin default. WebSocket mode is useful when the API cannot expose an inbound URL, but it currently needs API configuration.

Prerequisites

CHANNELS_ENABLED=true on the API service
PUBLIC_API_BASE_URL set to the public HTTPS API URL for webhook mode
LARK_OPEN_BASE_URL=https://open.feishu.cn for Feishu, or the matching Lark Open Platform base URL for your region
An existing NCA agent
A Feishu or Lark custom app with bot capability enabled

Create the app

Open the Feishu or Lark Open Platform console.
Create a custom app.
Enable the bot capability.
Copy the App ID and App Secret.
Publish the app version after changing permissions or event subscriptions.

Recommended permissions:

Permission area	Why
Read messages sent to the bot in DMs	Receive private messages.
Read group messages or group mentions	Receive group messages.
Send messages as bot	Send agent replies and progress cards.
Read bot or chat metadata	Let health checks verify bot identity.

The exact scope names differ between Feishu and Lark consoles, but they are the im:* bot messaging scopes.

Webhook mode

Webhook mode receives platform callbacks at:

{PUBLIC_API_BASE_URL}/api/channels/hooks/lark/{channelId}

Configure the app’s event subscription or callback Request URL to this inbound URL and subscribe to:

Event	Why
`im.message.receive_v1`	Receive user messages.

For webhook security, configure either Verification Token or Encrypt Key in both the Open Platform console and NCA. If encryptKey is set in NCA, encrypted callbacks are required.

WebSocket mode

WebSocket mode uses the Lark SDK long connection client. It does not need PUBLIC_API_BASE_URL or webhook verification, but the app still needs the same bot permissions and im.message.receive_v1 event subscription.

Create the channel through the API with subscriptionMode set to websocket. NCA starts the WebSocket client when the active channel is loaded.

Configure in Admin

Open Admin, then go to Channels.
Create a new channel and choose Lark / Feishu.
Select the agent that should receive messages.
Enter a label, App ID, App Secret, and webhook security values.
Create the channel.
Copy the inbound URL from the channel detail page and paste it into the Open Platform event subscription Request URL.

The channel becomes active after the platform verifies the webhook URL.

API payload: webhook

{
    "agentId": "agt_...",
    "provider": "lark",
    "label": "engineering-feishu",
    "config": {
        "appId": "cli_...",
        "subscriptionMode": "webhook",
        "verificationToken": "...",
        "encryptKey": null,
        "mentionOnly": true,
        "shareSessionInChannel": false,
        "threadIsolation": false,
        "progressMode": "preview",
        "botName": "Netmind Cloud Agent"
    },
    "credentials": {
        "appSecret": "..."
    }
}

API payload: WebSocket

{
    "agentId": "agt_...",
    "provider": "lark",
    "label": "engineering-feishu-ws",
    "config": {
        "appId": "cli_...",
        "subscriptionMode": "websocket",
        "verificationToken": null,
        "encryptKey": null,
        "mentionOnly": true,
        "shareSessionInChannel": false,
        "threadIsolation": false,
        "progressMode": "preview",
        "botName": "Netmind Cloud Agent"
    },
    "credentials": {
        "appSecret": "..."
    }
}

Configuration

Field	Required	Default	Notes
`appId`	Yes	None	Feishu or Lark App ID, usually starting with `cli_`.
`subscriptionMode`	No	`webhook`	`webhook` receives HTTP callbacks. `websocket` starts a long connection client.
`verificationToken`	Webhook security	`null`	Used to verify unencrypted callbacks.
`encryptKey`	Webhook security	`null`	Used to decrypt encrypted callbacks. If set, NCA rejects unencrypted callbacks.
`mentionOnly`	No	`true`	In groups, only respond when the bot is mentioned. Private chats always respond.
`shareSessionInChannel`	No	`false`	When `true`, users in the same group share one agent session unless a thread scope is used.
`threadIsolation`	No	`false`	Uses message root or thread IDs as the group session scope when available.
`progressMode`	No	`preview`	`preview` sends and updates an interactive progress card. `final` only sends the final reply.
`botName`	No	`null`	Bot display name used to detect group mentions. Set this when `mentionOnly=true`.

Credentials

Field	Required	Notes
`appSecret`	Yes	App Secret from the Open Platform console. Stored encrypted.

Verify

Use the channel detail page test action, or call:

curl -X POST "$NCA_API_URL/channels/{channelId}/test" \
    -H "Authorization: Bearer $NCA_TOKEN"

A healthy webhook channel reports valid credentials and an active or verified webhook status. A healthy WebSocket channel reports valid credentials and a recent WebSocket connection.

Troubleshooting

Webhook verification fails: check PUBLIC_API_BASE_URL, Verification Token, Encrypt Key, and the exact inbound URL.
WebSocket never connects: verify the App ID, App Secret, region domain, app publication state, and event subscription.
Group messages are ignored: set botName to the bot display name, mention the bot, or set mentionOnly=false.
Bot identity check fails: publish the app version and confirm messaging scopes are approved.