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

Brand	Region	Domain
feishu	China mainland (中国大陆)	feishu.cn / accounts.feishu.cn
lark	International	larksuite.com / accounts.larksuite.com

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

action	required params	purpose
status	—	Current Feishu/Lark app state. Use to check if already connected.
connect	brand (optional, default "feishu")	Start device flow. Returns verification URL + device_code.
poll	device_code, brand	Check if user has confirmed authorization. Returns status.
disconnect	—	Unbind Feishu/Lark app (destructive — confirm with user first).

---

Channel-aware QR / link display

User channel	How to show
Web	Include file_path (QR image) in your reply — frontend renders it inline. Also show the link.
Telegram	send_to_telegram(file_path=<qr_path>, message_type="photo") + include the link in the caption
WeChat	Show the link only (user can't scan a QR inside WeChat for Feishu)
Feishu	(User is already on Feishu — they don't need to bind. Tell them it's already connected or check status.)

---

Key differences from WeChat / Telegram

Aspect	Feishu/Lark	WeChat	Telegram
Auth method	Device flow (URL)	QR code scan	Bot token
User action	Open URL + confirm in app	Scan QR + confirm	Create bot via @BotFather
Credential	None (device flow handles it)	bot_token (from QR)	bot_token (from BotFather)
Brand choice	feishu / lark	N/A	N/A

---

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

Symptom	Likely cause	Fix
connect returns error	User already has an active app	Call status first; if active, ask if they want to disconnect and rebind
poll returns expired	User took too long to confirm	Start a new connect
poll returns pending repeatedly	User hasn't opened the URL yet	Remind them to open the verification URL
User says "I can't find the link"	URL was in a previous message	Re-run connect to get a fresh URL