Feishu / Lark Adapter

The Feishu adapter is fully implemented and supports connecting to onebots service through Feishu/Lark Open Platform Bot API. It supports both Feishu (China) and Lark (International).

Status

✅ Implemented and Available

Features

• ✅ Messaging and interactions: direct/group messages, replies, message/thread forwarding, rich posts, static cards, media, contact cards, reactions, follow-up bubbles, urgent notifications, and pins
• ✅ CardKit v1: card entity creation and delivery, full/batch/settings updates, element lifecycle, and streamed text updates
• ✅ Message management: fetch, recall, card updates, read users, and batch-message status management
• ✅ Chat management: chat details, members, managers, share links, and announcements
• ✅ Directories: bot identity, visible contact users, and verified chat members
• ✅ Event ingress: official long connection, webhook, and manual host integration; unknown events remain available through raw_event
• ✅ Reliability: shared tenant-token refresh, event deduplication, guarded cursor pagination, and structured platform errors
• ✅ Multi-Endpoint Support
  • Feishu (China)
  • Lark (International)
  • Custom endpoint (private deployment)

Installation

Open Extensions in the Web console and select the adapter, or run:

onebots ui --data-dir <workspace> --setup

The manager installs the adapter and its required peer dependencies into a verified immutable runtime generation. Do not run package-manager install commands directly in the OneBots runtime directory.

Configuration

Configure Feishu/Lark account in config.yaml:

# Feishu bot account configuration (China, default)
feishu.feishu_bot:
  app_id: 'your_app_id'  # App ID, required
  app_secret: 'your_app_secret'  # App Secret, required
  receive_mode: long_connection  # long_connection | webhook | manual
  encrypt_key: 'your_encrypt_key'  # Optional, event encryption key
  verification_token: 'your_verification_token'  # Optional, event verification Token
  
  # OneBot V11 protocol configuration
  onebot.v11:
    access_token: 'your_v11_token'

# Lark bot account configuration (International)
feishu.lark_bot:
  app_id: 'your_app_id'
  app_secret: 'your_app_secret'
  endpoint: 'https://open.larksuite.com/open-apis'  # Lark endpoint
  
  # OneBot V11 protocol configuration
  onebot.v11:
    access_token: 'your_v11_token'

Configuration Options

Option	Type	Required	Description
app_id	string	Yes	Feishu/Lark App ID
app_secret	string	Yes	Feishu/Lark App Secret
receive_mode	string	No	Event ingress mode; defaults to long_connection
encrypt_key	string	No	Event encryption key
verification_token	string	No	Event verification Token
endpoint	string	No	API endpoint, defaults to Feishu China

Endpoint Configuration

Endpoint	URL	Description
Feishu (default)	https://open.feishu.cn/open-apis	China
Lark	https://open.larksuite.com/open-apis	International

TypeScript Configuration

When using TypeScript, you can import endpoint constants:

import { FeishuEndpoint } from '@onebots/adapter-feishu';

// Feishu (China) - endpoint can be omitted
{
  account_id: 'feishu_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
}

// Lark (International)
{
  account_id: 'lark_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
  endpoint: FeishuEndpoint.LARK,
}

// Private deployment
{
  account_id: 'private_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
  endpoint: 'https://your-private-feishu.com/open-apis',
}

Getting App Credentials

Feishu (China)

1. Visit Feishu Open Platform
2. Create an enterprise self-built application
3. Get App ID and App Secret
4. Select the official long connection, or configure the Webhook URL: http://your-server:port/feishu/{account_id}/webhook
5. Configure application permissions (messaging, contacts, etc.)

Lark (International)

1. Visit Lark Developer
2. Create an application and get credentials
3. Configuration is the same as Feishu, just set endpoint to Lark endpoint

Client SDK Usage

import { createOnebot12Client } from '@imhelper/onebot-v12';

const client = createOnebot12Client({
  baseUrl: 'http://localhost:6727/feishu/your_bot_id/onebot/v12',
  apiBaseUrl: 'http://localhost:6727/feishu/your_bot_id/onebot/v12',
  wsUrl: 'ws://localhost:6727/feishu/your_bot_id/onebot/v12',
  selfId: 'your_bot_id',
  accessToken: 'your_access_token',
  receiveMode: 'ws',
});

client.on('message.group', async message => {
  await message.reply('Received!');
});

await client.start();

CardKit platform actions

Use the protocols' shared platform-action entry point to call create_card_entity, send_card_entity, update_card_entity, update_card_settings, batch_update_card, create_card_elements, update_card_element, patch_card_element, stream_card_element_content, and delete_card_element. These actions accept structured card objects and serialize the JSON strings required by Feishu/Lark. Mutations require an explicit non-negative integer sequence; an optional uuid provides idempotency.

Creating and mutating card entities requires cardkit:card:write; sending them requires im:message. See the adapter README for the complete parameters and examples.

Related Links

• Feishu Open Platform
• Lark Developer
• Feishu Adapter Configuration
• Quick Start
• Client SDK Guide