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
Start device flow:feishu(action="connect", brand="feishu") — returns verification_uri, device_code, and a QR code image saved to workspace.
Show BOTH options to the user:
QR code scan: Display the QR code image inline using the markdown_image from the result (e.g. ). 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.
Wait for the user to confirm. Don't auto-poll — let them say "done" / "confirmed" / "已确认" / "scanned" first.
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.
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.
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
