# Connect Feishu (Lark) Bot (/docs/channels/feishu)
Buda natively supports Feishu bots via persistent WebSocket connections. **No public webhook URL or tunneling required** — just provide your App ID and App Secret.
> Lark (international) tenants: use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in your config.
***
Step 1: Create a Feishu App [#step-1-create-a-feishu-app]
1.1 Open Feishu Open Platform [#11-open-feishu-open-platform]
Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.
1.2 Create an enterprise app [#12-create-an-enterprise-app]
1. Click **Create enterprise app**
2. Fill in the app name, description, and icon
3. Click **Create**
1.3 Copy credentials [#13-copy-credentials]
From **Credentials & Basic Info**, copy:
```
App ID: cli_xxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
> App Secret is hidden by default — click "View" to reveal it. Keep it private.
1.4 Configure permissions [#14-configure-permissions]
In **Permissions**, click **Batch import** and paste:
```json
{
"scopes": {
"tenant": [
"aily:file:read",
"aily:file:write",
"application:application.app_message_stats.overview:readonly",
"application:application:self_manage",
"application:bot.menu:write",
"cardkit:card:read",
"cardkit:card:write",
"contact:user.employee_id:readonly",
"contact:contact.base:readonly",
"corehr:file:download",
"event:ip_list",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource"
],
"user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
}
}
```
1.5 Publish the app (first time) [#15-publish-the-app-first-time]
**You must publish before enabling event subscriptions.**
1. Go to **Version Management & Release** → **Create Version**
2. Set version to `1.0.0`, click **Save** → **Submit for release**
3. Wait for approval (enterprise apps usually auto-approve)
***
Step 2: Configure the channel in Buda [#step-2-configure-the-channel-in-buda]
Open Buda's Channel settings, select **Feishu**, enter your App ID and App Secret, and save.
Buda immediately establishes a WebSocket long connection to Feishu in the background.
> ⚠️ Complete this step before configuring event subscriptions — Feishu needs to detect the active connection first.
***
Step 3: Enable event subscription [#step-3-enable-event-subscription]
1. Go to **Event Subscription** → **Event Configuration**
2. Enable **Use long connection to receive events**
3. Click **Add Event** and add `im.message.receive_v1`
4. Click **Save**
> ⚠️ If the long connection toggle is grayed out, the app hasn't been published yet. Complete step 1.5 first.
***
Step 4: Publish a new version [#step-4-publish-a-new-version]
After adding events, publish a new version for changes to take effect:
1. **Version Management & Release** → **Create Version**, increment the version (e.g. `1.0.1`)
2. Click **Save** → **Submit for release**
***
Step 5: Test [#step-5-test]
1. Open Feishu and find your bot
2. Send a message, e.g. `Hello`
3. The bot replies — you're all set 🎉
***
Troubleshooting [#troubleshooting]
Bot does not respond [#bot-does-not-respond]
| Possible cause | Solution |
| --------------------- | ------------------------------------------- |
| Event not added | Check that `im.message.receive_v1` is added |
| Missing permissions | Review step 1.4 |
| Wrong credentials | Verify App ID and App Secret in Buda |
| Version not published | Publish a new version after adding events |
Long connection cannot be enabled [#long-connection-cannot-be-enabled]
The app hasn't been published. Complete step 1.5 and wait 1–2 minutes before retrying.
App Secret leaked [#app-secret-leaked]
1. Reset the App Secret in Feishu Open Platform
2. Update the App Secret in Buda
3. Restart the gateway
***
Supported message types [#supported-message-types]
Receive [#receive]
* ✅ Text, rich text
* ✅ Images, files, audio, video
* ✅ Stickers
Send [#send]
* ✅ Text, images, files, audio, video
* ✅ Interactive cards (streaming output)
***
Configuration reference [#configuration-reference]
| Setting | Description | Default |
| ------------------------------------------------- | ------------------------------- | ----------- |
| `channels.feishu.enabled` | Enable/disable channel | `true` |
| `channels.feishu.domain` | API domain (`feishu` or `lark`) | `feishu` |
| `channels.feishu.connectionMode` | Event transport mode | `websocket` |
| `channels.feishu.defaultAccount` | Default account ID | `default` |
| `channels.feishu.accounts..appId` | App ID | - |
| `channels.feishu.accounts..appSecret` | App Secret | - |
| `channels.feishu.dmPolicy` | DM policy | `pairing` |
| `channels.feishu.allowFrom` | DM allowlist (open\_id) | - |
| `channels.feishu.groupPolicy` | Group policy | `open` |
| `channels.feishu.groupAllowFrom` | Group allowlist | - |
| `channels.feishu.groups..requireMention` | Require @mention | `true` |
| `channels.feishu.textChunkLimit` | Message chunk size | `2000` |
| `channels.feishu.mediaMaxMb` | Media size limit | `30` |
| `channels.feishu.streaming` | Enable streaming card output | `true` |
| `channels.feishu.typingIndicator` | Enable typing indicator | `true` |
| `channels.feishu.resolveSenderNames` | Resolve sender names | `true` |