KocoroKocoro
Download
Integration

Lark / Feishu Integration Guide

This guide walks you through creating a custom app on the Lark (Feishu) Open Platform — enabling the bot capability, API permissions, and event/callback subscriptions — and registering it in Kocoro. Once done, your team can message the bot or @mention it in Lark / Feishu chats and your agent replies.

Before you begin

  • A Lark / Feishu account allowed to create custom apps.
  • Kocoro installed and initialized, with at least one agent created.
  • Network access to the Lark / Feishu Open Platform and Kocoro services.
  1. 1

    Create a custom app

    Sign in to the Lark Open Platform (open.larksuite.com/app, or open.feishu.cn/app for Feishu), then click "Create Custom App".

    Fig. 1 — Click "Create Custom App" on the Lark / Feishu Open Platform.
  2. 2

    Fill in the app info and create

    In the dialog, enter the app name and description, choose or upload an app icon, then click "Create".

    Fig. 2 — Enter the app name, description and icon, then click Create.
  3. 3

    Copy the App ID and App Secret

    Open the app's console and go to "Credentials & Basic Info" in the left sidebar. Copy the App ID and App Secret — these credentials let Kocoro connect to Lark / Feishu.

    Keep the App Secret safe — if it leaks, reset it on the same page.
    Fig. 3 — Copy the App ID and App Secret on Credentials & Basic Info.
  4. 4

    Add the Lark / Feishu bot in Kocoro

    Open Kocoro, go to Capabilities → Connectors, and click "Add Bot" under "Lark" / "Feishu". In the dialog (step 1/3) paste the App ID and App Secret from the previous step, then click "Next".

    Feishu does not support one-click OAuth — please use app credentials.
    Fig. 4 — Enter the App ID and App Secret in Kocoro (step 1/3).
  5. 5

    Get the Encrypt Key

    Go to "Events & Callbacks → Encryption Strategy", click "Reset" on Encrypt Key to generate one, then paste it into Kocoro.

    Fig. 5 — Reset and copy the Encrypt Key under Encryption Strategy.
  6. 6

    Add the Bot capability

    Back in the Lark / Feishu console, go to "Add Features" and click "Add" on the "Bot" card. This lets the app send and receive messages in Lark / Feishu as a bot.

    Fig. 6 — Add the Bot capability under Add Features.
  7. 7

    Enable API permissions

    Go to "Permissions & Scopes" and click "Add permission scopes". Paste the scope list below into the search box, select all, then click "Add Scopes" (10 scopes total).

    im:resource,contact:contact.base:readonly,contact:user.base:readonly,im:message.group_at_msg:readonly,im:message.p2p_msg:readonly,im:message:send_as_bot,im:message,cardkit:card:write,im:message:readonly,im:message.reactions:read
    You can also click "Open permissions page" in Kocoro's Add Bot dialog — it pre-fills these scopes automatically.
    Fig. 7 — Batch-add the 10 scopes under Permissions & Scopes.
  8. 8

    Finish registration in Kocoro

    Back in Kocoro's Add Feishu Bot dialog (step 2/3): paste the Encrypt Key from step 5 into the "Get Encrypt Key" field; confirm "Add Bot" and "Configure permissions" are done (use the links to double-check); pick the agent under "Choose Agent", optionally set a "Display Name", then click "Register Bot".

    Fig. 8 — Paste the Encrypt Key, pick an agent and register the bot in Kocoro (step 2/3).
  9. 9

    Set the event request URL

    Go to "Events & Callbacks → Event Configuration", set the subscription mode to "Send notifications to developer's server", enter the URL below in "Request URL", and save.

    https://api.shannon.run/api/v1/channels/feishu/events
    Fig. 9 — Choose "Send notifications to developer's server" and enter the request URL.
  10. 10

    Add the Message received event

    On the Event Configuration page click "Add Events", search for and select "Message received (im.message.receive_v1)", then click "Add".

    im.message.receive_v1
    Fig. 10 — Add the Message received event.
  11. 11

    Set the callback request URL

    Switch to the "Callback Configuration" tab, set the subscription mode to "Send callbacks to developer's server", enter the same URL in "Request URL", and save.

    https://api.shannon.run/api/v1/channels/feishu/events
    Fig. 11 — Choose "Send callbacks to developer's server" and enter the request URL.
  12. 12

    Add the Card callback

    On the Callback Configuration page click "Add callback", under the "Card" category select "Card callback communication (card.action.trigger)", then click "Add".

    card.action.trigger
    Fig. 12 — Add the Card callback communication.
  13. 13

    Publish the app to apply the config

    Finally, in the Lark / Feishu console go to "Version Management & Release", set the availability scope and click "Save" to create a version and publish. The config only takes effect after the app is published (and admin-approved).

    If the banner says "The current configuration will take effect after the app is published.", this step is required.
    Fig. 13 — Save and publish the app under Version Management & Release.

Done — start using it in Lark / Feishu

After the app is published and connected, members within the visibility scope can message the bot in Lark / Feishu, or @mention it in a group, and the selected agent replies. To use it in a group, add the bot to that group.

← Help Center
Open Lark ConsoleOpen Feishu Console