--- title: "Feishu / Lark Platform" type: entity tags: [platform, feishu, gateway, intermediate, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-feishu.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Feishu / Lark** (飞书 in China, Lark internationally) is one of the most fully featured Hermes platforms: interactive approval cards, rich markdown posts, media in both directions, emoji-reaction state feedback, and per-group access policies. Platform support landed in v0.6.0; v0.9.0 added the standout **scan-to-create** onboarding — `hermes gateway setup` shows a QR code and auto-creates the bot app with correct permissions. Two connection modes: `websocket` (recommended, outbound connection, no public URL) and `webhook` (HTTP push with signature verification). ## Characteristics - **Credentials:** `FEISHU_APP_ID=cli_xxx`, `FEISHU_APP_SECRET=secret_xxx`; `FEISHU_DOMAIN=feishu` (China) or `lark` (international). Manual route: open.feishu.cn / open.larksuite.com → create app → enable Bot capability. - **Connection modes:** `FEISHU_CONNECTION_MODE=websocket` (Lark SDK maintains a persistent outbound connection; needs `websockets` package; tune `ws_reconnect_interval` (default 120 s) / `ws_ping_interval` under `platforms.feishu.extra`) or `webhook` (`aiohttp` server at `/feishu/webhook`, tunable via `FEISHU_WEBHOOK_HOST=127.0.0.1`, `FEISHU_WEBHOOK_PORT=8765`, `FEISHU_WEBHOOK_PATH`). URL-verification challenges are answered automatically. - **Access control:** `FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy` (open_ids); `FEISHU_GROUP_POLICY=open|allowlist|disabled` (default `allowlist`); fine-grained per-group `group_rules` in `config.yaml` (`open | allowlist | blacklist | admin_only | disabled` + global `admins` list, plus `default_group_policy` fallback). Groups require an `@mention` by default — disable globally with `FEISHU_REQUIRE_MENTION=false` or per-chat with `require_mention: false` on a `group_rules` entry; DMs bypass the gate. - **Bot-to-bot:** other bots' messages are ignored by default; `FEISHU_ALLOW_BOTS=none|mentions|all` (default `none`) opts into A2A orchestration — peer bots bypass the human allowlist; grant `application:bot.basic_info:read` to show peer bot names. - **Meeting invitations:** invite the bot to a Feishu/Lark video meeting like a human participant — the `vc.bot.meeting_invited_v1` event hands the agent the meeting number and it attempts to auto-join, provided the inviter passes normal allowlist/pairing checks. - **Webhook security:** `FEISHU_ENCRYPT_KEY` enables `SHA256(timestamp + nonce + encrypt_key + body)` signature checks against `x-lark-signature` (timing-safe); `FEISHU_VERIFICATION_TOKEN` checks the payload token — and gates URL-verification challenges too; both can be combined. Per-IP rate limiting (120 req/60 s window, HTTP 429), 1 MB body cap, 30 s read timeout, JSON-only, anomaly warning after 25 consecutive errors from one IP in 6 h. `require_webhook_auth_secret` (added in v0.15.0). - **Interactive cards / approvals:** approval prompts arrive as cards with Allow Once / Session / Always / Deny buttons; clicks route back as synthetic `/card` commands. **Three console steps are mandatory** — subscribe to `card.action.trigger`, enable the Interactive Card capability, and (webhook mode) set the Message Card Request URL — or button clicks fail with **error 200340**. - **Media:** inbound images/audio/video/files downloaded and cached (small `.txt`/`.md` content auto-injected into the message); outbound `send_image_file`, `send_document`, `send_voice`, `send_video`; markdown auto-sent as rich **post** messages with plain-text fallback. - **Feedback & batching:** processing-status reactions — `Typing` while working, cleared on reply or `CrossMark` on failure; disable with `FEISHU_REACTIONS=false` (added in v0.11.0). Text batching (0.6 s quiet period, 8 msgs / 4000 chars max, `HERMES_FEISHU_TEXT_BATCH_*` env vars) and media batching (0.8 s) with per-chat serialization; 24 h message dedup (cache size `HERMES_FEISHU_DEDUP_CACHE_SIZE=2048`) persisted to `~/.hermes/feishu_seen_message_ids.json`; card actions deduped over a 15-minute window. - **Bot identity for mention gating:** `FEISHU_BOT_OPEN_ID` / `FEISHU_BOT_USER_ID` / `FEISHU_BOT_NAME`, or auto-discovery with the `admin:app.info:readonly` scope. - **Home chat:** `/set-home` in a chat, or `FEISHU_HOME_CHANNEL=oc_xxx` for cron output and notifications. - **Later additions:** intelligent reply on document comments with 3-tier access control (added in v0.11.0); operator-configurable bot admission + mention policy (added in v0.13.0); native update prompt cards (added in v0.14.0); SDK lazy-installs (added in v0.14.0). - **Toolset:** `hermes-feishu` — same core tools as Telegram and other gateway platforms. ## How to Use 1. Run the wizard and scan the QR with the Feishu/Lark mobile app (scan-to-create builds the app with correct permissions automatically): ```bash hermes gateway setup ``` 2. Or configure manually in `~/.hermes/.env`: ``` FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=secret_xxx FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy FEISHU_HOME_CHANNEL=oc_xxx ``` 3. In the Feishu Developer Console: subscribe to `card.action.trigger`, enable Interactive Card, and grant `im:message` + `im:resource` scopes for media. 4. Start the gateway and message the bot: ```bash hermes gateway ``` Common gotchas: error 200340 on card buttons (missing console config above); only one local gateway can use the same app_id; missing SDK → `pip install lark-oapi`. ## Related Entities - [[entities/platform-dingtalk]], [[entities/platform-wecom]] — sibling Chinese-ecosystem enterprise platforms - [[entities/platform-slack]] — Western counterpart with similar approval-button UX - [[concepts/messaging-gateway]] — gateway core; Feishu card approvals are one of its three native approval-button platforms - [[concepts/approval-system]] — Allow Once / Session / Always / Deny card flow - [[entities/version-v0.6.0]] — Feishu/Lark platform support added - [[entities/version-v0.9.0]] — QR scan-to-create onboarding added