om-scogo 📱 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 channelsskills/wechat-binding/SKILL.md— analogous WeChat flowskills/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
- Start device flow:
feishu(action="connect", brand="feishu")— returnsverification_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_imagefrom the result (e.g.). The user scans it with their Feishu/Lark app. - Direct link: Show the
verification_urlas a clickable link. The user opens it in their browser, logs in to Feishu/Lark, and confirms.
- QR code scan: Display the QR code image inline using the
- 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 withconnect.
- 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 |
| 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 | 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
pollreturnsexpired, tell the user and start a newconnect. disconnectis destructive — confirm with the user before calling it. It will stop the Feishu/Lark gateway instance.- Brand matters —
feishuandlarkuse 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
disconnectfirst, thenconnectwith 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 |