Lark Integration

Connect a custom Lark bot to Vuon so your team can ask questions, continue conversations, receive charts, and use approved Lark Docs, Base, and Calendar context without leaving Lark. This integration is currently an operator-assisted beta.

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

1. In the Lark Developer Console, create a Custom App in your organization's tenant.
2. Give the app a recognizable name, such as Vuon.
3. Add or enable the Bot capability.
4. 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:

Use tenant-token permissions rather than user-token permissions for these scopes.

3. Add optional read-only context permissions

Request only the capabilities your organization is enabling:

Base and Calendar are separately flagged betas. Existing bot or Docs customers do not need these additional scopes unless they opt in. Vuon does not request Base or Calendar write scopes and does not create, edit, RSVP to, subscribe to, or sync records and events.

Add optional scopes as user-token scopes, not tenant-token scopes. After changing scopes, publish a new app release if Lark shows unpublished changes.

4. Configure events and encryption

1. In Event Subscriptions, subscribe to the Message received event (im.message.receive_v1).
2. Enable encrypted event delivery.
3. Record the app's Verification Token and Encryption Key.
4. 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

1. Create and publish a release of the app.
2. Initially restrict app availability to the users who will test the integration.
3. Confirm those users can find the bot and start a direct message with it.
4. 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.

Enable read-only workspace context

Workspace context uses a separate Lark user authorization in addition to the bot credentials. Vuon support will coordinate the authorization after the app has the selected user-token scopes.

Choose the context identity

The current beta is a shared organization connection:

• One clearly named Lark user authorizes the connection.
• Vuon can read only resources visible to that user and explicitly allowlisted for the Vuon organization.
• Everyone who can use the Vuon organization may ask the agent to use that shared context. It does not switch to the Lark identity of the person asking.
• primary means the authorizing user's primary calendar.

Use a managed Lark account whose access is limited to the information intended for shared Vuon use. Do not authorize a personal executive or employee account unless its visible context is deliberately meant to be shared with the Vuon organization.

Choose exact sources

Provide Vuon support with only the sources the shared identity should expose:

• Base: the full table or view URL, such as https://your-tenant.larksuite.com/base/<app-token>?table=<table-id>. A view can be narrowed further with its view parameter.
• Calendar: primary for the authorizing user's primary calendar, or an explicit Lark calendar ID.

An allowlist entry is required before Vuon exposes the corresponding tool. A different Base table, view, or calendar is denied before Vuon calls Lark.

Authorize and activate

1. Tell Vuon support which capabilities to enable: Docs, Base, Calendar, or a combination.
2. Provide the exact Base URLs and calendar IDs to allowlist.
3. Vuon support opens a short-lived authorization link for your organization.
4. Sign in to Lark as the chosen shared context identity and approve the listed read-only scopes.
5. Vuon verifies the returned scopes, saves the encrypted renewable grant, and enables only the selected organization flags.
6. Validate with one known Base record and one known calendar event before expanding the app's availability.

Adding Base or Calendar later requires an administrator to add the new scope to the tenant-owned Lark app and reauthorize the shared connection. Existing bot customers are not prompted and receive no new access until they opt in.

Vuon support may also ask your Lark administrator to register an exact organization-specific callback such as https://<org-slug>.vuon.ai/api/lark-docs/auth/callback in the app's Security Settings. This callback completes the shared authorization on the intended Vuon organization; it does not grant any additional Lark scope.

What Vuon reads and stores

Vuon fetches allowlisted context live when an agent needs it. It does not create a dataset, index, background sync, or event subscription for this context. Base and Calendar access is read-only: Vuon cannot change records, create or edit events, send invitations, or RSVP. OAuth tokens are encrypted and remain separate from the bot's tenant credentials.

What Vuon support configures

After receiving the app details securely, Vuon support will:

1. Store the app credentials encrypted with AWS KMS and scoped to your Vuon organization.
2. Associate the Lark App ID with that organization.
3. Enable the per-organization lark_bot_enabled beta flag.
4. Validate callback verification, user identity resolution, direct messages, group mentions, replies, and chart delivery.

When Base or Calendar context is enabled, support also records the exact Base table/view URLs and calendar IDs the shared authorization may access. Calendar primary belongs to the named authorizing identity; it is not automatically the calendar of each person using the bot.

These are Vuon-side steps; you do not need to change production configuration or feature flags yourself.

How to use the bot

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.

Requests can include screenshots and files. Send an image or a file, or paste images into a rich-text message; Vuon opens images and files up to 25 MB from the same conversation. In a group, put the image in a rich-text message that mentions the bot, or reply with it in the bot's thread. Voice messages, videos, and stickers are ignored.

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.

Base or Calendar context is unavailable

• Confirm the scope is listed as User token / Added in the Lark app.
• Confirm the shared Lark identity can open the exact Base URL or calendar.
• Confirm the Base URL or calendar ID was included in the Vuon allowlist.
• If a capability was added after the original authorization, ask Vuon support to reauthorize the shared connection and enable that capability's flag.
• Remember that primary refers to the shared authorizing identity, not the person asking the question.

FAQ

Related documentation

• Slack Integration
• Team Setup Guide
• Account Settings