Feishu (Lark) Bridge #

Hagency's in-house bridge for Feishu — ByteDance's enterprise communication suite (known internationally as Lark). Like the DingTalk bridge, Feishu's protocol is closed, so this is a webhook + open-API bridge rather than full session emulation.

It works equally well for feishu.cn (mainland China) and larksuite.com (international) — just pick the right endpoint when you configure credentials.

Prerequisites #

  • Hagency plan: Enterprise
  • Admin access to a Feishu / Lark workspace
  • A Feishu app you can create (or have already created) in the Feishu open platform with Bot capability enabled
  • Your app's app_id, app_secret, and verification_token

Enable the bridge #

  1. Dashboard → Server → Bridges → Feishu → Enable.
  2. Wait ~10 seconds. The bot appears at @feishubot:<your-name>.hagency.cloud.
  3. The dashboard shows a webhook URL: https://<your-name>.hagency.cloud/bridges/feishu/webhook. Copy it.

Configure Feishu #

Step 1 — Create the Feishu app #

  1. Go to open.feishu.cn (or open.larksuite.com for the international edition) and sign in.
  2. Developer Console → Create custom app.
  3. Fill in name, icon, description. Save.
  4. Open the new app and copy App ID and App Secret.

Step 2 — Enable Bot capability + events #

  1. In the left sidebar, Features → Bot → Enable.
  2. Events & callbacks → Event Subscription: paste the Hagency webhook URL from step 1.
  3. Feishu validates the URL (your bridge endpoint replies with the required challenge token).
  4. Subscribe to these events:
    • im.message.receive_v1 (incoming messages)
    • im.chat.member.user.added_v1
    • im.chat.member.user.deleted_v1
    • im.chat.updated_v1
  5. Save. The verification_token and encrypt_key appear at the top of the page — copy both.

Step 3 — Grant the required API scopes #

Still in the developer console, under Permissions & scopes, enable:

  • im:message (send + receive messages)
  • im:chat (read chat metadata)
  • im:chat:readonly
  • im:message.group_at_msg (if you want @ mentions to work)
  • im:resource (upload images/files)

Save, then submit the app for your workspace administrator to approve.

DM @feishubot:<your-name>.hagency.cloud:

login <app_id> <app_secret> <verification_token> <encrypt_key> <region>

Where <region> is either cn (feishu.cn) or intl (larksuite.com).

The bot validates the app with Feishu's open API and replies Logged in: <workspace-name>.

Step 5 — Install the app to a chat #

  1. In Feishu, open the target chat (group or 1:1).
  2. Click Settings → Add bot → Custom bot.
  3. Select your newly created app.
  4. The bot posts a confirmation message in the chat. The bridge detects it and begins mirroring messages for that chat.

What gets bridged #

  • Group chats → Matrix rooms (one per Feishu chat).
  • 1:1 DMs → Matrix DM rooms.
  • Text, rich text, markdown, mentions, replies → bidirectional.
  • Images and files → bidirectional.
  • Feishu cards (interactive JSON cards) → rendered as Matrix markdown + attachment links.
  • Reactions → bidirectional (Feishu now supports reactions on newer tenants).
  • Video calls / 妙记 / 文档 → NOT bridged (separate products with separate APIs).

Commands reference #

CommandWhat it does
login <app_id> <app_secret> <verification_token> <encrypt_key> <region>Link a Feishu app
logoutUnlink
statusShow last event + API health
chatsList bridged chats
helpFull command list

Limitations #

  • Per-chat activation. Like DingTalk, the bot has to be explicitly added to each chat you want bridged — there's no "discover all chats" API.
  • Edits. Feishu lets you edit messages for up to an hour after sending. Edits before that window are bridged; edits after (rare) are not.
  • Deletions. Delete events are bridged. The Matrix message is redacted.
  • Read receipts. Feishu's read receipts don't surface via the open API, so they don't flow to Matrix.
  • Workspace-switching. A single bridge login is tied to one Feishu tenant. Use multiple logins if you're in multiple tenants.

Troubleshooting #

"Event verification failed" — Feishu challenges the webhook with a one-time token during event setup. If Hagency's endpoint can't be reached (firewall, paused workspace, etc.) this fails. Fix the network path and re-save the event subscription.

"App scope missing" — log in to the Feishu developer console and double-check all required scopes are approved by the workspace admin. Newly added scopes need re-approval.

Messages one-way only — verify the app is actually installed in the chat (step 5). Without the bot presence, outgoing messages from Matrix have nowhere to land.

login fails with invalid region — cn for feishu.cn, intl for larksuite.com. Nothing else is accepted.

Privacy considerations #

  • All API traffic between Hagency and Feishu uses HTTPS with the encryption key you supplied.
  • app_secret and encrypt_key are encrypted at rest in your workspace.
  • Unlinking deletes stored credentials and stops processing events.

What's next #