Lark / Feishu
Connect Lark or Feishu when you want an agent available from private chats, groups, or team workflows in a Lark / Feishu workspace.
Prerequisites
- An existing Cloud Agents agent.
- Permission to create or manage a custom app in the Lark or Feishu Open Platform.
- Bot capability enabled for the app.
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.
Event subscription
Subscribe the app to message events:
| Event | Why |
|---|---|
im.message.receive_v1 | Receive user messages. |
Cloud Agents can use webhook delivery or long-connection delivery, depending on what your workspace supports. Webhook mode is the usual setup for most users.
For webhook security, configure either a Verification Token or Encrypt Key in both the Open Platform console and Cloud Agents.
Connect it to Cloud Agents
- Open Settings -> 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.
- Paste it into the Open Platform event subscription Request URL.
- Publish the app version after changing permissions or subscriptions.
- Run the channel test.
Recommended settings
| Setting | Recommendation |
|---|---|
| Mention only | Keep on for groups so the agent replies only when mentioned. |
| Bot name | Set the bot display name so group mentions are detected reliably. |
| Shared session | Keep off unless everyone in the group should share one conversation. |
| Progress mode | Use preview for an updating progress card while the agent works. |
Verify
Open the channel detail page and run Test. A healthy channel confirms valid app credentials and recent delivery status.
Troubleshooting
- Webhook verification fails: confirm the Verification Token or Encrypt Key, then paste the current inbound URL from Cloud Agents.
- Messages do not arrive: confirm
im.message.receive_v1is subscribed and the app version is published. - Group messages are ignored: set the bot display name, mention the bot, or turn off mention-only mode.
- Bot identity check fails: confirm the App ID, App Secret, region, and approved messaging scopes.