Skip to main content
Lark Trigger binds a Lark integration to a Digital Expert workflow, enabling the flow of “send a message in Lark, route it to the selected Digital Expert in Xpert AI”. The Lark integration stores App ID, App Secret, Webhook, or long-connection settings. The Lark trigger decides which Digital Expert should process incoming messages.

​
Applicable scenarios

  • Trigger a Digital Expert from Lark direct chats or group chats.
  • Use enterprise IM as a unified Digital Expert entry point.
  • Restrict which users or groups can trigger the Digital Expert.
  • Aggregate several short messages before sending them to the Digital Expert.
  • Read Lark message context or image resources during a conversation.

​
Key configuration

Core Lark Trigger configuration:
  • enabled: whether the trigger is enabled
  • integrationId: Lark integration instance ID (required)
  • sessionTimeoutSeconds: session timeout, default 3600 seconds
  • summaryWindowSeconds: message aggregation window, default 0 seconds
  • singleChatScope: direct-chat scope, all_users or selected_users
  • singleChatUserOpenIds: allowed user Open IDs when direct-chat scope is selected users
  • allowedGroupScope: group-chat scope, all_chats or selected_chats
  • allowedGroupChatIds: allowed group chat IDs when group scope is selected chats
  • groupReplyStrategy: group reply strategy, mention_only or all_messages
Validation before publish checks:
  1. Whether a valid Lark integration is selected.
  2. Whether the current integration is already bound to another Digital Expert (to avoid conflicts).
  3. When the trigger is enabled, one Lark integration can only be bound to one Digital Expert at a time.

​
Setup flow

  1. Create and test a Lark integration.
  2. Open the target Digital Expert workflow.
  3. Add Lark Trigger.
  4. Select the Lark integration you created.
  5. Configure direct-chat scope, group-chat scope, group reply strategy, session timeout, and message aggregation window.
  6. Connect the trigger to downstream Agent, toolset, or knowledge-base nodes.
  7. Publish the Digital Expert workflow.
After publishing, Xpert AI persists the integrationId -> xpertId binding. When a Lark message arrives, the platform first finds the target Digital Expert by this binding, then enters workflow execution.

​
Runtime mechanism

  1. Publish phase
    • Validate that the selected Lark integration exists.
    • Check whether the same integration is already occupied by another Digital Expert.
    • Write or update the Lark trigger binding.
    • Register the current runtime callback.
  2. Message arrival phase
    • Webhook mode receives Lark events from POST /api/lark/webhook/<integrationId>.
    • Long-connection mode receives im.message.receive_v1 and card.action.trigger events from the Lark long-connection service.
    • The plugin parses chat ID, sender Open ID, message content, and image/file resources.
  3. Routing phase
    • Find the trigger binding by integrationId.
    • Apply direct-chat scope, group-chat scope, and group reply strategy.
    • If the message is not allowed, it will not enter the Digital Expert.
  4. Execution phase
    • If the runtime callback is available, advance the current workflow directly.
    • If the callback is unavailable, such as after restart, enter the persistent handoff queue.
    • After the Digital Expert finishes, reply through the Lark context.

​
Session and message aggregation

sessionTimeoutSeconds controls how long the Lark conversation continues the same Digital Expert session. If the user is idle longer than this value, the next message starts a new Digital Expert session. summaryWindowSeconds merges several short messages:
  • 0: every message triggers the Digital Expert immediately.
  • Greater than 0: messages in the same conversation are buffered during this window and merged into one input.
If another message arrives during the aggregation window, the aggregation version is refreshed and only the newest version is dispatched, avoiding duplicate processing from old windows.

​
Group chat trigger strategy

Lark groups default to mention_only, meaning only messages that mention the bot trigger processing. all_messages sends all group messages through trigger filtering and is only suitable for dedicated bot groups. If only some groups should trigger the Digital Expert, set allowedGroupScope to selected_chats and choose the allowed groups in allowedGroupChatIds.

​
FAQ

​
The bot does not reply after saving the Lark integration

Check:
  • The target Digital Expert has added and published Lark Trigger.
  • The trigger is enabled and selects the Lark integration used by the current bot.
  • In group chats, the message mentions the bot, or groupReplyStrategy is set to all_messages.
  • The Lark app subscribes to im.message.receive_v1.
  • In Webhook mode, the callback URL is publicly reachable.
  • In long-connection mode, the status page shows connected.

​
User or group selectors are empty

Selectors depend on the Lark integration to read contacts and group chats. Check whether the Lark app has contact/group read permissions and whether the app version has been published again.

​
Image messages do not reach the model

Lark images are read through message resources and converted into files visible to the Digital Expert. Make sure the app has message-resource read permission and the target model supports vision input.

​
Startup recovery strategy

Lark Trigger uses bootstrap.mode = skip:
  • It does not replay publish at startup.
  • It relies on persistent bindings and external message events to resume processing.
This approach is suitable for triggers continuously driven by external events and avoids duplicate registration.