Feishu

Last updated 10/07/2026

Prerequisites

1. Feishu Open Platform configuration

1. Go to Feishu Open Platform

2. Create a custom app (or use an existing app)

3. Get the app credentials:

   • App ID (application ID)
   • App Secret (application secret)

2. Configure the bot

On Feishu Open Platform, go to App details > Features > Bot and enable the bot feature.

3. Configure the redirect URL

On Feishu Open Platform, go to App details > Security Settings > Redirect URLs and add:

http://your-domain/agent/api/feishu-oauth/callback

4. Events and callbacks

Subscription mode: On Feishu Open Platform, go to Events & Callbacks and select Receive through persistent connection for both events and callbacks. You don't need to configure a public request URL.

1. Event configuration: Add im.message.receive_v1 (Receive messages v2.0) to receive messages, images, and files that users send to the bot.
2. Callback configuration: Add card.action.trigger (card action callback) to handle submitting, ignoring, and continuing AskUserQuestion forms.
3. App permissions: Must include im:resource (download users' images/files and upload generated files) and cardkit:card:write (create, stream-update, and replace interactive cards). Without im:resource, text messages may work normally, but reading images and sending generated files will fail.
4. Save and publish: After any change to permissions, events, or callbacks, you must create and publish a new version in Version Management & Release, and make sure that the availability scope includes the target users. Saving the development configuration alone doesn't make the installed version take effect.

tip

Verification tips: After you start the channel, first confirm that the persistent connection succeeded, and then test plain text, image reading, AskUserQuestion form submission, and generated files as native attachments, in that order.

5. Configure app permissions

On Feishu Open Platform, go to App details > Permissions & Scopes and apply for the following permissions:

Message permissions (Bot Token Scopes):

Permissions	Description
im:message	Send messages
im:message.group_at_msg:readonly	Read messages that @mention the bot in group chats
im:message.group_msg	Send group messages
im:message.p2p_msg:readonly	Read direct messages
im:message:send_as_bot	Send messages as the bot
im:message:readonly	Read messages
im:resource	Get and upload image or file resources
cardkit:card:write	Create and update cards

User identity permissions (User Token Scopes):

Permissions	Description
contact:user.base:readonly	Get basic user information (required for authentication)

After you apply for the permissions, an admin needs to approve them.

Bulk import:

{

"scopes": {

"tenant": [

"im:message",

"im:message.group_at_msg:readonly",

"im:message.group_msg",

"im:message.p2p_msg:readonly",

"im:message:readonly",

"im:message:send_as_bot",

"im:resource",

"cardkit:card:write"

],

"user": [

"contact:user.base:readonly"

]

}

}

tip

Double-check when you bulk import permissions: The import result must include im:resource and cardkit:card:write. If an older JSON doesn't include these two, add them in Permissions & Scopes and publish a new app version.

Recommended additional permission for group chat message routing: tenant:tenant:readonly (get tenant information). With this permission, System Admin can identify the tenant and show the group chat space right after the channel is verified. Without it, credential verification and message sending and receiving still work, but the group chat space is discovered only after the first message that @mentions the bot arrives from the target group. After you add the permission, publish a new app version and click Verify Again in Channels.

6. Publish the app

On Feishu Open Platform, go to App details > Version Management & Release and set the app availability scope & publish the app

Select the employees to authorize. Only employees within the availability scope can use the app

The app is available after the review is approved.

Agent configuration

1. Configure the channel

Configure the channel in System Admin:

1. Log in to the system and go to System Admin > Agent Management > Channels

2. Click New Channel and select Feishu as the type

3. Fill in the configuration:

   • Channel Name: A custom name (such as "Feishu Bot")
   • APP ID & APP Secret

4. Click Save. The system automatically encrypts and stores the configuration

5. Enable the channel (make sure the Enable switch is on)

Note:

• The configuration is encrypted and stored in the database for better security
• When the application starts, it automatically connects to all enabled Feishu channels (through WebSocket persistent connections)
• Configuration changes take effect immediately without restarting the service

How to use

Bind a user account

1. Log in to the system
2. Click your avatar in the lower-left corner to open the menu
3. Select Channel Accounts, find the channel instance you want to bind under Feishu, and click Bind
4. You're redirected to the Feishu authorization page
5. Confirm the authorization
6. You're automatically redirected back to the system, and the Binding successful page appears
7. Close the authorization window. The original page refreshes automatically, and the menu shows the Bound status

Unbind a user account

1. Click your avatar in the lower-left corner to open the menu
2. Select Channel Accounts, find the bound channel instance under Feishu, and click Unbind
3. Confirm the unbinding
4. After unbinding succeeds, the menu shows the Unbound status

User guide

Custom commands

The Feishu bot supports the following commands (all commands start with /):

Command	Description	Example
/new	Starts a new session and clears the current session history	Send /new
/agent <名称> <消息>	Sends a message to the Agent with the specified name	/agent rhea 你好
/agent <消息>	Sends a message to the system default Agent	/agent 你好

Notes:

• Messages that don't start with / are sent directly to the system default Agent
• The Agent name must be an Agent that the user has permission to access
• Command parameters are case-sensitive

Group chat message routing

Group chat message routing lets the same Feishu bot hand different questions to different Agents or Teams based on rules. A Group Chat Space corresponds to the current Feishu tenant, and the configuration applies to group chats in that tenant that use this bot. Only members who have bound an Agentic Engine account and explicitly @mention the bot in the group can start tasks.

Admin setup

1. Make sure that the channel is enabled, the app is published, and im.message.receive_v1 and card.action.trigger are subscribed. We recommend adding tenant:tenant:readonly so that the system can identify the Feishu tenant when it verifies the channel. Without it, you need to first send a message that @mentions the bot in the target group before the system can discover the group chat space.
2. Go to System Admin > Agent Management > Channels and open Message Routing on the corresponding Feishu channel. If there are multiple group chat spaces, first select the space you want to configure.
3. Select the Default Agent/Team. You must configure the default before you enable group chat routing. Regular messages that don't match any other rule are handed to it.
4. Add up to 19 rules as needed. For each rule, select an Agent/Team, fill in the required Command, and optionally add up to 10 keywords. Then turn on the enable switch of the rule.
5. After saving, send @机器人 /help in the group to verify the setup. Make sure the list shows only the Agents/Teams that the current user can use and that can currently run.

Config items	Rule
Default Agent/Team	Required before routing can be enabled. Used when no command is specified and no keyword is matched.
Command	Required, 1–32 characters. You can use letters, digits, -, and _, but not system-reserved commands. Differences in letter case or between full-width and half-width characters don't make commands distinct.
Keywords	Optional. Up to 10 per rule, each 2–32 characters. When multiple keywords match at the same time, the longer keyword takes priority. If no unique match can be determined among rules of the same length, the default Agent/Team is used.
Available options	You can select enabled and runnable system/company Agents, as well as Teams in the current company. Personal Agents don't appear as group chat routing candidates.

Use in group chats

Purpose	Example	Description
View available capabilities	@机器人 /help @机器人 能力清单	Lists the default, commands, and keywords. Capabilities that you don't have permission for or that can't currently run aren't shown.
Specify an Agent/Team	@机器人 /analysis 分析本周数据	analysis is a command configured by the admin. You can also send @机器人 @analysis 分析本周数据.
Route by keyword	@机器人 帮我检查埋点方案	When the message text matches a rule's keyword, it's handed to the corresponding Agent/Team. Otherwise, the default is used.
Cancel a task	@机器人 /cancel	Must be sent exactly as the entire message. Text that the task has already output is kept, and you receive a separate cancellation confirmation.
Legacy syntax	@机器人 /agent analysis 分析本周数据	Still supported, but new documentation recommends using /analysis directly.

Command scope: Group chat routing doesn't support /new. Direct messages still support /new, /agent, and /cancel. In group chats, you must @mention the bot to start a regular new task. Only when an existing task is waiting for an answer can you continue replying in the original thread or interactive card as the bot prompts.

Public context and personal data: For reference, the system uses only recent public group chat turns that explicitly @mentioned the bot and were actually processed. Regular group messages that don't @mention the bot, other groups, direct messages, and personal memories are never mixed in. History serves only as untrusted reference, and only the current message is the instruction for this turn.

Troubleshooting

1. Callback URL error

Error message: The redirect URL is incorrect. Contact the app admin

Solution:

• Check that the callback URL configured on Feishu Open Platform is correct
• Make sure that the protocol, domain, port, and path match exactly
• For local development, check the port number (such as 3000 vs 8686)
• If you use NEXT_PUBLIC_BASE_PATH, the callback URL must include that path

2. Feishu channel not configured

Error message: Feishu channel is not configured or not enabled

Solution:

• Go to System Admin > Agent Management > Channels and check whether the Feishu channel exists
• Make sure that the Enable switch of the channel is on
• Check that the App ID and App Secret are entered correctly
• Make sure that the app type is a custom app

3. Invalid App Access Token

Error message: The app access token passed is invalid

Solution:

• Check that the App ID and App Secret in Channels are correct
• Confirm the app type (custom app)
• Check whether the app is enabled

4. Insufficient permissions

Error message: Insufficient permissions or permission verification failed

Solution:

• Apply for the required permissions on Feishu Open Platform
• Wait for an admin to approve the permissions
• Make sure that the permissions have taken effect

5. Binding failure

Error message: This Feishu account is bound to another user

Solution:

• A Feishu account can be bound to only one system user
• To change the binding, first unbind it from the original account

Related documents

• Feishu Open Platform documentation

---

Related pages and next steps

• See the setup instructions for other platforms: Channel management.
• Learn about the overall flow of channel connection and binding: Channel overview and binding.
• Configure the Agent to use: Agent.
• See how to use conversations in the platform: Conversations.