Feishu (Lark) Integration

The Feishu integration connects your Feishu workspace to Mopheus via a WebSocket long-connection hub. Once configured, agents respond to Feishu messages in real time, and any ticket that originates from a Feishu chat receives status-change and comment notifications back in that same chat.

SetupCopy Anchor Link

Inbound voice messages (audio) are downloaded using their file_key as file resources and stored as attachments. This does not automatically transcribe audio. See the Feishu resource download API.

1. Configure MopheusCopy Anchor Link

In Settings → System Config, set the following:

Do not change the Lark secret key after saving app credentials. The current key decrypts existing credentials, and changing it prevents existing Lark installations from connecting. | Lark Domain (lark_domain) | feishu.cn (default, China) or larksuite.com (international Lark) |

2. Register the InstallationCopy Anchor Link

In your workspace's Settings → Integrations → Feishu, click Connect Feishu App. Scan the QR code with the Feishu mobile app to authorize the installation. Mopheus stores the app credentials (encrypted with lark_secret_key) and starts a WebSocket long connection to Feishu's event push service.

Installing the app authorizes the installation; it does not automatically make the bot available to every Feishu user. In the Feishu Open Platform, publish the app and configure its availability range or tenant authorization to include every user who should use the bot. Users outside that range may receive a Feishu availability error before Mopheus can process their message.

Group Chat AccessCopy Anchor Link

The integration can read the group name when the app has im:chat:read, but it cannot currently inspect group-chat messages or context proactively. To read group messages or group-chat context, add the im:message.group_msg permission to the Feishu app:

1. Open the Feishu Open Platform and select the custom app.
2. Open Permissions & Scopes and search for im:message.group_msg or “Get all messages in group chats”.
3. Add and save the permission.
4. Publish a new app version with the permission change. For an app that is already installed, complete the app authorization or configuration update flow again.
5. Return to Mopheus and confirm that the Feishu integration uses the updated app authorization.

Without this permission, Mopheus can still process messages delivered directly to the bot, but it cannot proactively query other messages in a group chat.

3. Bind a Feishu UserCopy Anchor Link

Each Feishu user who wants to chat with agents must link their Feishu account to their Mopheus account. The first time you message the bot, Mopheus sends a one-time binding link. Open it, sign in to Mopheus, and the accounts are linked. Once bound, all messages you send in Feishu are dispatched to your assigned agent on your behalf.

Platform availability and Mopheus account binding are separate requirements: a user must first be allowed to use the Feishu app, then complete the one-time Mopheus binding flow.

Feishu / Lark OAuth SSO LoginCopy Anchor Link

In addition to the bot messaging integration, Mopheus supports logging in with a Feishu account. Once configured, a Login with Feishu / Lark button appears on the login page.

PrerequisitesCopy Anchor Link

You need a Feishu app dedicated to OAuth login (this can be the same app as the bot, or a separate one).

1. Create the App in Feishu Open PlatformCopy Anchor Link

1. Go to Feishu Open Platform → Developer Console → create a custom app

2. Under Permissions & Scopes, enable:

   • contact:user.id:readonly (required — fetches the user's open_id)
   • contact:user.email:readonly (optional but recommended — used to match existing accounts by email)

3. Under Security Settings, add a redirect URL:

   • Production: https://app.example.com/auth/lark/callback
   • Local dev: http://localhost:3000/auth/lark/callback (Feishu allows localhost)

   Use the frontend URL (app_url). The frontend callback page exchanges the code with the backend via a POST API call.

4. Publish the app (self-built apps typically take effect immediately)

2. Configure MopheusCopy Anchor Link

In Settings → System Config, set:

Once saved, the Login with Feishu / Lark button appears on the login page automatically — no restart needed.

Account MatchingCopy Anchor Link

Lark CLI Configuration and Credential StorageCopy Anchor Link

The Lark CLI app configuration and user credentials are stored separately. The two Mopheus personal runtime configuration templates are listed together here:

User authorization credentials and the App Secret are stored in the keychain, not in config.json:

Copying only config.json on macOS or Windows does not migrate the user login. Configure the app on the destination device, then run lark-cli auth login again.

How It WorksCopy Anchor Link

Inbound: Feishu → MopheusCopy Anchor Link

Feishu user sends message
        │
        ▼
Feishu event push (im.message.receive_v1)
        │
        ▼
Mopheus WebSocket hub (per installation)
        │
        ▼
Dispatcher: look up chat session & agent
        │
        ├─ No binding yet → send binding URL to user
        │
        └─ Binding found → enqueue agent task
                │
                ▼
           Agent runs, produces reply
                │
                ▼
           Patcher sends reply to Feishu chat

Chat session naming — session titles are always Chinese:

• P2P chat: 与 {sender name} 的对话 (falls back to 飞书对话 when the sender name is unavailable)
• Group chat: uses the group name if provided, otherwise 飞书群聊

Sessions are deduplicated per (installation, chat ID). If a binding row is found but the session no longer exists in the database, a fresh session and binding are created automatically.

Outbound: Mopheus → FeishuCopy Anchor Link

The Patcher component handles all outbound traffic. It is wired up only when lark_enabled = true.

{prefix} is the ticket identifier prefix auto-derived from the workspace slug (uppercased, up to 10 characters; e.g. slug dba-team → prefix DT). The full comment content is sent — it is not truncated. System comments (status-change notes) are not forwarded — only regular comments.

Message FormatCopy Anchor Link

Text reply (no markdown detected): sent as msg_type=text, renders as a normal IM message.

Markdown reply (bold, code blocks, headers, links, etc.): sent as an interactive card (msg_type=interactive) with a markdown element so Feishu's client renders the formatting. This is not a Feishu msg_type=markdown message.

Error card: rendered as a red interactive card with the agent name in the header and the error detail in the body.

Streaming output: Mopheus does not continuously update the same interactive card. It sends the final reply once the task completes and shows only a processing indicator while the task is running.

TroubleshootingCopy Anchor Link