Lark

Last updated 10/07/2026

Prerequisites

1. Lark Open Platform configuration

• Go to Lark Open Platform

• Create a custom app (or use an existing app)

• Get the app credentials:

  • APP ID
  • APP Secret

2. Configure the bot

• On Lark Open Platform, go to Add Features → Add by feature → Bot

3. Configure the redirect URL

• On Lark Open Platform, go to Security Settings → Redirect URLs → Add

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

For local testing, the redirect URL is: http://localhost:3000/api/lark-oauth/callback

4. Events and callbacks

• Subscription mode: In Events & Callbacks in the Lark Developer Console, choose to receive both events and callbacks through a persistent connection. You don't need to fill in a public Callback URL. Add im.message.receive_v1 to the event configuration, and add card.action.trigger to the callback configuration to handle submitting, ignoring, and continuing AskUserQuestion forms. The 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. After you change permissions, events, or callbacks, you must create and publish a new version, and make sure the app is available to the target users.

5. Configure app permissions

• Lark Open Platform → Permissions & Scopes → click Add permission scopes → enable the following in Tenant token scopes:

im:message	Read and send direct and group messages
im:message.group_at_msg.include_bot:readonly	Read messages in groups in which other bots and users @mention the current bot
im:message.group_at_msg:readonly	Read messages in groups in which users @mention the bot
im:message.group_msg	Read all messages in groups
im:message.p2p_msg:readonly	Read direct messages that users send to the bot
im:message:readonly	Read direct and group messages
im:message:send_as_bot	Send messages as the app
im:resource	Get and upload image or file resources
cardkit:card:write	Create and update cards

Recommended additional permission for group chat message routing: tenant:tenant:readonly (Read 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.

• Enable the following in User token scopes:
  • contact:user.base:readonly (get basic user information)
• Click Confirm to add the permissions

6. Publish the app

• Lark Open Platform → Version Management & Release → set the app availability scope and publish the app

Agent configuration

Configure the channel in System Admin:

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

• Click New Channel and select Lark as the type

• Fill in the configuration:

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

• Click Save

• 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 Lark channels (through WebSocket persistent connections)
• Configuration changes take effect immediately without restarting the service

How to use

Bind a user account

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

Unbind a user account

• Click your avatar in the lower-left corner to open the menu
• Select Channel Accounts, find the bound channel instance under Lark, and click Unbind
• Confirm the unbinding
• After unbinding succeeds, the menu shows the Unbound status

User guide

Custom commands

The Lark 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 <name> <message>	Sends a message to the Agent with the specified name	/agent rhea hello
/agent <message>	Sends a message to the system default Agent	/agent hello

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 Lark Bot hand different questions to different Agents or Teams based on rules. A Group Chat Space corresponds to the current Lark 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 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 Lark 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 @Bot /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	@Bot /help @Bot 能力清单	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	@Bot /analysis 分析本周数据	analysis is a command configured by the admin. You can also send @Bot @analysis 分析本周数据.
Route by keyword	@Bot 帮我检查埋点方案	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	@Bot /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	@Bot /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 Lark 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: Lark channel is not configured or not enabled

Solution

• Go to System Admin → Agent Management → Channels and check whether the Lark 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 Lark Open Platform
• Wait for an admin to approve the permissions
• Make sure that the permissions have taken effect

---

5. Binding failure

Error message: This Lark account is bound to another user

Solution

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

Related documents

• Documentation - Lark Developer

---

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.