Skip to main content
Feishu (Lark internationally) integration uses WebSocket long connection, eliminating the need for a public IP or webhook configuration.

​
Features

  • ✅ WebSocket long connection (no public IP required)
  • ✅ App ID and App Secret authentication
  • ✅ Open ID-based access control
  • ✅ Private and group message support
  • ✅ Optional encryption and verification

​
Setup

1

Create a Feishu bot

  1. Visit Feishu Open Platform
  2. Click Create App (创建应用)
  3. Choose Custom App (自建应用)
  4. Fill in app name and description
  5. Enable Bot capability (机器人)
2

Configure permissions

In Permissions & Scopes (权限管理):Add these permissions:
  • im:message — Send messages (发送消息)
  • im:message.p2p_msg:readonly — Receive private messages (接收私聊消息)
Click Apply and wait for approval if required.
3

Configure event subscription

In Event Subscriptions (事件订阅):
  1. Add event: im.message.receive_v1 (接收消息)
  2. Important: Select Long Connection mode (长连接模式)
  3. Save configuration
Long Connection requires nanobot to be running before events can be received
4

Get credentials

In Credentials & Basic Info (凭证与基础信息):Copy:
  • App ID (format: cli_xxx)
  • App Secret
Optional (for webhook mode only):
  • Encrypt Key (加密密钥)
  • Verification Token (验证令牌)
5

Publish the app

  1. Go to Version Management & Release (版本管理与发布)
  2. Create a version and submit for review
  3. Or publish to internal users only (员工可见)
6

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": ["ou_YOUR_OPEN_ID"]
    }
  }
}
encryptKey and verificationToken are optional for Long Connection mode
7

Start the gateway

nanobot gateway
You should see:
Feishu channel connected via WebSocket
8

Find your Open ID

  1. Message your bot in Feishu
  2. Check nanobot logs — it will display the sender’s Open ID
  3. Copy the Open ID and add it to allowFrom in config
  4. Restart gateway if needed
Alternatively, use ["*"] to allow all users (not recommended for production).

​
Configuration Options

​
enabled
boolean
required
Enable the Feishu channel
​
appId
string
required
App ID from Feishu Open Platform (format: cli_xxx)
​
appSecret
string
required
App Secret from Feishu Open Platform
​
encryptKey
string
default:""
Encrypt Key for message encryption (optional for Long Connection mode)
​
verificationToken
string
default:""
Verification Token for webhook validation (optional for Long Connection mode)
​
allowFrom
array
required
List of Feishu Open IDs allowed to interact with the botExamples:
  • Single user: ["ou_abc123"]
  • Multiple users: ["ou_abc123", "ou_def456"]
  • All users: ["*"] (not recommended for production)
Find Open IDs in nanobot logs when users message the bot

​
WebSocket vs Webhook

Feishu supports two ways to receive events:
  • ✅ No public IP required
  • ✅ No SSL certificate needed
  • ✅ Works behind firewall/NAT
  • ✅ Simpler setup
  • This is what nanobot uses by default

​
Webhook (HTTP)

  • ❌ Requires public IP
  • ❌ Requires HTTPS with valid certificate
  • ❌ More complex setup
  • Only use if you have specific webhook requirements

​
Troubleshooting

  1. Check permissions: Verify im:message and im:message.p2p_msg:readonly are approved
  2. Check Open ID: Ensure your Open ID is in allowFrom
  3. Check event subscription: Must be set to Long Connection mode
  4. Check app status: App must be published (at least to internal users)
  5. Check logs: Run nanobot gateway -v for detailed logs
  1. Verify App ID and App Secret are correct
  2. Check internet connectivity
  3. Ensure no firewall blocks WebSocket connections
  4. Try restarting gateway: nanobot gateway
  5. Check Feishu Open Platform status
If you see permission errors:
  1. Go to Feishu Open Platform → Your App → Permissions
  2. Verify all required permissions are added and approved
  3. Some permissions require admin approval
  4. Wait for approval, then restart gateway
To get your Open ID:
  1. Temporarily set allowFrom: ["*"]
  2. Restart gateway
  3. Send a message to the bot
  4. Check logs — Open ID will be displayed
  5. Copy the Open ID and add it to allowFrom
  6. Remove "*" and restart gateway
Common issues:
  1. Webhook mode selected: Change to Long Connection in event settings
  2. Gateway not running: Start gateway before events can be received
  3. Event not added: Ensure im.message.receive_v1 is added
  4. App not published: Publish app to at least internal users

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a1b2c3d4e5f6g7h8",
      "appSecret": "abcdefghijklmnopqrstuvwxyz123456",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": ["ou_abc123def456"]
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us