Lark Integration
Connect a custom Lark bot to Vuon so your team can ask questions, continue conversations, and receive charts without leaving Lark. This integration is currently an operator-assisted beta.
Lark setup is coordinated with Vuon support. There is not currently a self-service Lark card in Vuon's Integrations settings.
How the integration is organized
Your organization will normally create and own a custom app in its own Lark tenant. A custom app belongs to the tenant where it was created, so Vuon's existing internal custom app cannot simply be reused in another customer's Lark tenant.
The current integration intentionally associates one Lark App ID with one Vuon organization. This gives each incoming message one deterministic destination and helps maintain tenant isolation.
Prerequisites
Before starting, make sure you have:
- Permission to create, configure, and publish a custom app in your Lark tenant
- A Vuon organization with the intended Lark users already invited
- A secure secret-sharing method approved by your organization
- A Vuon support contact to coordinate activation and callback validation
Set up the Lark app
Lark console labels can vary slightly by region or console version. Use the equivalent custom-app, permission, event, and release controls in your tenant.
1. Create a custom app and enable the bot
- In the Lark Developer Console, create a Custom App in your organization's tenant.
- Give the app a recognizable name, such as Vuon.
- Add or enable the Bot capability.
- Record the App ID. You will use it in the callback URL and provide it to Vuon support.
2. Add tenant-token permissions
In the app's permissions section, add the following scopes for the tenant access token:
| Scope | Why Vuon needs it |
|---|---|
im:message | Work with Lark messages |
im:message:send_as_bot | Send bot replies |
im:message:update | Update bot progress messages |
im:message.p2p_msg:readonly | Read direct messages sent to the bot |
im:message.group_at_msg:readonly | Read group messages that mention the bot |
im:resource | Upload message resources, including chart images |
contact:contact.base:readonly | Read the basic contact directory needed for identity lookup |
contact:user.base:readonly | Read basic user details |
contact:user.email:readonly | Match a Lark user to their Vuon account by email |
Use tenant-token permissions rather than user-token permissions for these scopes.
3. Add read-only Docs permissions
On the same custom app, also request these scopes now:
| Scope | Why Vuon will need it |
|---|---|
drive:drive:readonly | Discover documents in Lark Drive |
wiki:wiki:readonly | Search Wiki and resolve Wiki nodes |
docx:document:readonly | Read Docx metadata and content |
offline_access | Refresh a user's authorization for continued access |
4. Configure events and encryption
- In Event Subscriptions, subscribe to the Message received event (
im.message.receive_v1). - Enable encrypted event delivery.
- Record the app's Verification Token and Encryption Key.
- Configure the request URL, replacing
<APP_ID>with the App ID from step 1:
https://lark-webhook.vuon.ai/api/webhooks/lark/<APP_ID>
5. Securely provide the app details to Vuon
Provide all four values to Vuon support through the secure transfer method they give you:
- App ID
- App Secret
- Verification Token
- Encryption Key
6. Publish with limited availability
- Create and publish a release of the app.
- Initially restrict app availability to the users who will test the integration.
- Confirm those users can find the bot and start a direct message with it.
- Expand availability only after your initial validation succeeds.
7. Check user email addresses
Vuon identifies a Lark user by looking up their Lark email address in the associated Vuon organization. Each tester's email address in Lark must therefore match an email address on their Vuon account.
What Vuon support configures
After receiving the app details securely, Vuon support will:
- Store the app credentials encrypted with AWS KMS and scoped to your Vuon organization.
- Associate the Lark App ID with that organization.
- Enable the per-organization
lark_bot_enabledbeta flag. - Validate callback verification, user identity resolution, direct messages, group mentions, replies, and chart delivery.
These are Vuon-side steps; you do not need to change production configuration or feature flags yourself.
How to use the bot
| Where | What to send | Behavior |
|---|---|---|
| Direct message | A normal request | Starts a conversation, or continues the current DM conversation |
| Direct message | /new <request> | Starts a fresh conversation with the supplied request |
| Direct message | An ordinary follow-up | Continues the current conversation without a command |
| Group conversation | @Vuon <request> | Starts a conversation for that group thread |
| Existing group thread | An ordinary reply | Continues the conversation in that thread; another mention is not required |
Put /new at the beginning of a direct message and include the request on the same message, for example: /new compare this month's revenue with last month.
Troubleshooting
The bot does not reply
- Confirm the app is published and available to the affected user.
- Confirm the Bot capability is enabled.
- In a group, mention the bot in the first message. Ordinary top-level group messages are intentionally ignored.
- Ask Vuon support to confirm that activation and validation are complete.
A user is not recognized
Confirm the user's Lark email address exactly matches an email address on their Vuon account and that the user belongs to the associated Vuon organization. Also verify that contact:user.email:readonly and the other contact scopes are approved for the app.
Text replies work, but charts fail
Confirm that the app has the im:resource tenant-token scope. Without it, Vuon cannot upload chart images to Lark. After changing permissions, publish a new app release if Lark requires one.
The user cannot find or open the bot
Check the published release's availability range. During initial testing, make sure the affected user is explicitly included in the allowed audience.
Callback validation or events fail
- Confirm the callback is exactly
https://lark-webhook.vuon.ai/api/webhooks/lark/<APP_ID>and contains the same App ID provided to Vuon. - Confirm encrypted event delivery is enabled and that Vuon has the current Verification Token and Encryption Key.
- Confirm the Message received event is subscribed.
- After changing scopes, events, credentials, or availability, publish a new release when required by Lark.
FAQ
Can we use Vuon's existing internal Lark app?
No. A Lark custom app is owned by the tenant where it was created and cannot simply be installed into an unrelated customer tenant. Your organization will normally create its own tenant-owned custom app.
Can one Lark app connect to multiple Vuon organizations?
Not in the current beta. One App ID is associated with one Vuon organization so routing is deterministic and tenant boundaries remain clear.
Can we make the bot available to everyone immediately?
You can expand availability after validation, but Vuon recommends starting with a small intended-user group so permissions, identity matching, and message delivery can be checked safely.