Skip to main content
Lark Integration stores credentials, event receiving mode, and runtime status for a Lark or Feishu internal app. It only connects Lark to Xpert AI. To route messages into a Digital Expert, you must also add and publish Lark Trigger in the target Digital Expert workflow. Current @xpert-ai/plugin-lark uses one integration provider, lark, and distinguishes Webhook and long connection through the Connection Mode field.
Lark is a communication plugin and must be installed at the tenant level. Tenant-level installation registers the Lark system integration provider, Webhook/long-connection entries, and Lark Trigger. If it is installed only at organization, project, or personal scope, creating integrations and triggers may not find the corresponding capabilities.

​
Connection modes

Default recommendation: use long connection (connectionMode=long_connection). Use Webhook only when you already have a stable public HTTPS callback URL or need to stay compatible with a Webhook deployment. Webhook mode generates this callback URL after saving:
Long-connection mode does not use this callback URL. Instead, the Xpert AI server connects outbound to the Lark Open Platform event channel.

​
Prepare the Lark app

  1. Log in to the Lark Developer Console.
  2. Create an internal enterprise app and enable the Bot capability.
  3. Copy credentials:
    • App ID
    • App Secret
  4. Choose event receiving mode:
    • Webhook mode: configure request URL and event subscriptions.
    • Long-connection mode: choose long connection for receiving events.
  5. Enable the app capabilities listed in “Event subscriptions” and “Required permissions” below.
  6. Publish the app version and set app availability for the required users or departments.

​
Event subscriptions

​
Required permissions

In the Lark Open Platform Permissions page, search by permission name and request the scopes below. After requesting permissions, publish a new app version and make sure users or departments receive the updated app authorization.

​
Create the integration in Xpert AI

Switch to the target organization that will use the Lark bot, then go to Settings -> System Integrations and create a Lark integration. System integrations are created at organization scope, and Lark triggers can only select integrations that exist in the current organization.

​
Required fields

​
Webhook fields

After saving or testing the integration, copy the Webhook URL from the test result and paste it into the Lark event subscription request URL. Webhook mode rejects callback requests for long-connection integrations, so update the Lark console when switching connection mode.

​
Long-connection fields

The long-connection test validates app credentials and bot info, then probes the Lark long-connection endpoint. If a newly saved long-connection integration does not connect immediately, wait for the plugin runtime to refresh or restart the plugin service.

​
Test result

After a successful test:
  • Webhook mode returns webhookUrl, which should be filled into the Lark console.
  • Long-connection mode returns probe fields such as probe.connected, probe.state, and probe.lastError.
If the test fails, check App ID, App Secret, whether the app version is published, whether bot capability is enabled, and whether the app is available to the current test user.

​
Status and session tabs

The Lark integration detail page provides extension tabs:
  • Status: connection mode, status, bot user, owner instance, last connected time, and recent errors.
  • Users: Lark users recorded or read by the plugin, used by trigger user selectors.
  • Sessions: Lark conversation bindings under this integration, including chat type, chat ID, sender Open ID, Digital Expert ID, conversation ID, and update time.
Long-connection mode supports refresh, reconnect, and disconnect on the status page. Webhook mode mainly depends on callback reachability and event subscription configuration.

​
Pair with Lark Trigger

After creating the integration:
  1. Open the target Digital Expert workflow.
  2. Add Lark Trigger.
  3. Select this Lark integration.
  4. Configure direct-chat scope, group-chat scope, group reply strategy, session timeout, and message aggregation window.
  5. Publish the Digital Expert.
If the trigger is not published, Lark events may reach Xpert AI but will not route to the target Digital Expert.

​
FAQ

​
Webhook URL verification failed

Check:
  • API_BASE_URL is a public HTTPS address.
  • The reverse proxy forwards /api/lark/webhook/<integrationId> to the Xpert API service.
  • The Lark console Verification Token matches the integration Verification Token.
  • Encrypt Key matches when encrypted events are enabled.

​
Long connection is not connected

Check:
  • The Lark console uses long connection for event receiving.
  • The server can access the Lark Open Platform long-connection endpoint.
  • App ID and App Secret belong to the same app.
  • The app version has been published and bot capability is enabled.

​
Selectors cannot list groups or users

Group selectors call the Lark group list API, and user selectors call the department user list API. Grant the required app permissions and publish the app again.