Feishu Binding

📱 Feishu/Lark Binding

Connect / disconnect the user's Feishu (飞书) or Lark account so the agent can chat via the Feishu/Lark app.

The feishu tool stays built-in. This SKILL.md is the reference doc.

See also

• config/context/references/messaging-channels.md — how messages are routed across channels
• skills/wechat-binding/SKILL.md — analogous WeChat flow
• skills/tg-bot-binding/SKILL.md — analogous Telegram flow

Brand selection

Ask the user which brand they use. Default to feishu if unclear. Chinese-speaking users almost always use feishu.

Typical binding flow

connect(brand) → user scans QR / opens link → poll(device_code) → done

1. Start device flow: feishu(action="connect", brand="feishu") — returns verification_uri, device_code, and a QR code image saved to workspace.
2. Show BOTH options to the user:
   • QR code scan: Display the QR code image inline using the markdown_image from the result (e.g. ![Feishu QR Code](feishu_qrcode_xxx.png)). The user scans it with their Feishu/Lark app.
   • Direct link: Show the verification_url as a clickable link. The user opens it in their browser, logs in to Feishu/Lark, and confirms.
3. Wait for the user to confirm. Don't auto-poll — let them say "done" / "confirmed" / "已确认" / "scanned" first.
4. Poll for completion: feishu(action="poll", device_code=<from step 1>, brand=<same brand>).
   • status: "done" → binding complete, congratulate the user.
   • status: "pending" → ask the user if they've scanned the QR code or opened the link and confirmed.
   • status: "expired" → the device flow expired (typically 5 minutes). Start over with connect.
5. Confirm to user: "Feishu/Lark connected! You can now chat with your agent on Feishu/Lark."

Actions

Channel-aware QR / link display

Key differences from WeChat / Telegram

Critical rules

• Don't auto-poll after connect. Wait for user confirmation that they've opened the link and confirmed in Feishu/Lark. Auto-polling wastes API calls.
• Device flow expires in ~5 minutes. If poll returns expired, tell the user and start a new connect.
• disconnect is destructive — confirm with the user before calling it. It will stop the Feishu/Lark gateway instance.
• Brand matters — feishu and lark use different API domains. Using the wrong brand will fail silently or redirect to the wrong login page.
• One app per user — a user can only have one Feishu/Lark app at a time. If they want to switch brands, they must disconnect first, then connect with the new brand.

Troubleshooting