Skip to content

IM Apps

IM Apps integrate with Lark to provide capabilities for Incident Warrooms, such as creating group chats, inviting members, synchronizing incident information, and responding to card actions.

Members with Workspace Management or Integration Management permissions can go to Integrations > IM Apps to view and manage connected apps. The app list displays app information and connection status, and supports searching by app name. Click an app to view its details.

Connect an App

Go to Integrations > IM Apps, click Connect App, and select Lark. Then follow the on-screen instructions to fill in the credentials and complete the Lark Open Platform configuration.

Connect Lark

1. Create a Lark App

  1. Log in to the Lark Open Platform and create an Enterprise Self-built App.
  2. Add Bot capability under App Capabilities.

2. Fill in App Parameters

Go to Integrations > IM Apps, click Connect App, and select Lark. Fill in the app name and the following parameters:

Field Required Description
App ID Yes Unique identifier of the Lark app
App Secret Yes Used to obtain the app access token; encrypted and not displayed
Verification Token Yes Used to verify whether the card callback originates from the current app
Encrypt Key Yes Used to decrypt card callback requests sent by Lark

The locations of each parameter in the Lark Open Platform are as follows:

  • App ID, App Secret: Go to Developer Console > Select App > Basic Info > Credentials & Basic Info.
  • Verification Token: Go to Developer Console > Select App > Development Config > Events & Callbacks > Encryption Policy, then copy the displayed Verification Token.
  • Encrypt Key: Also obtained from the Encryption Policy page. If it shows Not Enabled, click Reset or Custom Edit to generate or set an Encrypt Key, then fill it in on the connection page. The values on both sides must be exactly the same, otherwise the callback request cannot be decrypted.

Lark Open Platform encryption policy page for Events & Callbacks, with the Verification Token hidden

3. Enable App Permissions

In the Permissions Management of the Lark Open Platform, enable the following permissions for the app:

Permission Purpose
im:chat Create, manage, and dismiss warroom group chats, invite members, and generate group share links
im:message Send and update incident cards
contact:user.id:readonly Match Lark users by email or phone number to automatically invite members
Configure Contact Data Scope

After enabling contact:user.id:readonly, you also need to configure the contact data scope that this permission can access:

  1. In Permissions Management, find contact:user.id:readonly, click Accessible Data Scope > Configure.
  2. In Contacts, select All Members, or specify the departments and members that are allowed to be accessed.
  3. Ensure the data scope includes all members who may be invited into the warroom.
Contact data scope must cover invited members

The system can only retrieve Lark user information within the authorized scope. If a member is not within the contact data scope of contact:user.id:readonly, the system cannot find that member by email or phone number, and will be unable to invite that member when creating a warroom group chat.

4. Configure Card Callback

After credential verification succeeds, the third step of the connection page will generate a Card Callback URL. Go to the Lark Open Platform's Development Config > Events & Callbacks > Callback Configuration and complete the following:

  1. Select Send callbacks to the developer server, and fill in the Card Callback URL generated on the connection page.
  2. Add the callback: card.action.trigger.

Lark Open Platform callback configuration page, selecting to send callbacks to the developer server

The card callback can be configured later: not configuring the callback does not affect the app showing as Connected or creating group chats, but card actions (e.g., claiming, closing) in the incident group chat will not be available temporarily.

5. Release the App

  1. Go to the Lark Open Platform's App Publishing > Version Management & Release, and click Create Version.
  2. Configure the app's Available Scope, selecting All Members or specifying the departments and members that are allowed to use the app.
  3. Ensure the available scope includes members who may create warrooms, act as incident handlers, or be invited into warrooms.
  4. Submit and complete the app release.
App available scope must cover warroom members

If a member is not within the app's available scope, they cannot use the app normally, and creating group chats or inviting members may fail. If you select partial members or departments, update the scope and re-release the app when personnel changes occur.

6. Complete the Connection

After completing the app credential verification, the connection is established, and the app status shows Connected. Go to the Callback Configuration in the app details to view the callback status or copy the callback URL.

View and Manage Apps

Click an app row to enter its details, where you can view basic information, connection status, warroom capabilities, and operation history.

  • The app details page provides Callback Configuration to view and copy the card callback URL.
  • The app name, App ID, App Secret, Verification Token, etc., can all be modified.
  • You can delete unwanted apps from the details page.

The Lark card callback URL can only be viewed and copied by workspace administrators with IM App management permissions. Operations such as viewing, copying, configuration changes, and app deletion are recorded in the audit log.

Deleting an app requires a second confirmation. After deletion, the configuration cannot be recovered, and the app cannot be used to create new warrooms; existing external group chats and access records are not affected.

Connection Status

Status Description
Pending Verification App credentials have not been verified and cannot be used to create warrooms
Connected Credentials and basic capabilities are verified successfully; can be used to create warrooms
Abnormal Connection Credentials are invalid, permissions are insufficient, or the app on the enterprise side is unavailable; cannot create new warrooms

Lark apps also display an independent Callback Configuration Status:

Status Description
Pending Configuration No verified card callback has been received; group chats can still be created, but card actions are not available
Normal A source-verified card callback has been received
Abnormal The callback is continuously unreachable, or signature verification/decryption fails; check the callback configuration on the Lark platform and in the app details

If the app connection is abnormal, check the credentials, app permissions, and app available scope according to the on-screen prompts. Existing warroom external group chats will not be automatically closed.

Frequently Asked Questions

Why can't the app be connected?

Follow the on-screen prompts to check the following:

  • Whether the app credentials are correct.
  • Whether the Lark app has added the Bot capability and released the app version.
  • Whether the Lark permissions, contact data permissions, and app available scope are fully configured.

Why can't a connected app create warrooms?

Only apps with Connected status can create warrooms. Go to the app details to view the connection status and operation history, and fix the configuration according to the error prompts.

Do I need to reconfigure platform permissions after changing the Secret?

If the App ID and the app itself remain unchanged, simply changing the App Secret usually does not require re-enabling platform permissions or the card callback. After saving the new App Secret, confirm that the app returns to Connected status.

Why is the Lark app connected but card operations are not working?

Go to the app details and check the Callback Configuration Status:

  • If the status is Pending Configuration: Configure the card callback URL on the Lark Open Platform and add the card.action.trigger callback.
  • If the status is Abnormal: Check the callback URL and confirm that the Verification Token and Encrypt Key exactly match the configuration on the Lark Open Platform.

Until the callback is restored, you can still create and join Lark group chats, but you cannot handle incident card actions within the group.

Further Reading

You may also be interested in:

Feedback

Is this page helpful?