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.

Setup

1. Configure Mopheus

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 Installation

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.

3. Bind a Feishu User

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 Login

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.

Prerequisites

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 Platform

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 Mopheus

In Settings → System Config, set:

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

Account Matching

How It Works

Inbound: Feishu → Mopheus

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 → Feishu

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.

Ticket Notifications

When an agent creates a ticket while handling a Feishu chat message, Mopheus records both the originating chat session and the immutable source chat message in ticket metadata. Every subsequent status change or regular comment replies to that original Feishu message, rather than the session's latest message. Tickets created before this source-message anchor existed fall back to a chat-level notification. The agent's completed chat reply is the single creation result for a normal message; /ticket additionally sends its immediate command confirmation.

When a /ticket command includes an attachment, Mopheus waits for the attachment to be stored before dispatching the ticket task. If retrieval fails, the ticket receives a regular comment describing the failure, which is sent back to the originating Feishu message; the task is then cancelled. Text-only /ticket commands are dispatched immediately.

Feishu chat message triggers an agent task
        │
        ▼
Agent creates a ticket
        │
        ▼
Ticket status changes or comment is added
        │
        ▼
Patcher replies to the original Feishu message

This flow applies to both quick-create tasks (where the ticket is the immediate output) and regular chat tasks (where the agent creates a ticket as part of its processing).

Message Format

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.

Troubleshooting