Skill: leecyang/feishu-interactive-cards (version 1.0.2)

--- name: feishu-interactive-cards version: 1.0.2 description: Create and send interactive cards to Feishu (Lark) with buttons, forms, polls, and rich UI elements. Use when replying to Feishu messages and there is ANY uncertainty - send an interactive card instead of plain text to let users choose via buttons. Automatically handles callbacks via long-polling connection. Use for confirmations, choices, forms, todos, polls, or any scenario requiring user interaction in Feishu. --- # Feishu Interactive Cards ## Core Principle **When replying to Feishu and there is ANY uncertainty: send an interactive card instead of plain text.** Interactive cards let users respond via buttons rather than typing, making interactions faster and clearer. ## When to Use **Must use interactive cards:** - User needs to make a choice (yes/no, multiple options) - Confirmation required before action - Displaying todos or task lists - Creating polls or surveys - Collecting form input - Any uncertain situation **Plain text is OK:** - Simple notifications (no response needed) - Pure data display (no interaction) - Confirmed command results **Example:** - Wrong: "I deleted the file for you" (direct execution) - Right: Send card "Confirm delete file?" [Confirm] [Cancel] ## Quick Start ### 1. Start Callback Server (Long-Polling Mode) ```bash cd E:\openclaw\workspace\skills\feishu-interactive-cards\scripts node card-callback-server.js ``` **Features:** - Uses Feishu long-polling (no public IP needed) - Auto-reconnects - Sends callbacks to OpenClaw Gateway automatically ### 2. Send Interactive Card ```bash # Confirmation card node scripts/send-card.js confirmation "Confirm delete file?" --chat-id oc_xxx # Todo list node scripts/send-card.js todo --chat-id oc_xxx # Poll node scripts/send-card.js poll "Team activity" --options "Bowling,Movie,Dinner" --chat-id oc_xxx # Custom card node scripts/send-card.js custom --template examples/custom-card.json --chat-id oc_xxx ``` ### 3. Use in Agent When Agent needs to send Feishu messages: ```javascript // Wrong: Send plain text await message({ action: "send", channel: "feishu", message: "Confirm delete?" }); // Right: Send interactive card await exec({ command: `node E:\\openclaw\\workspace\\skills\\feishu-interactive-cards\\scripts\\send-card.js confirmation "Confirm delete file test.txt?" --chat-id ${chatId}` }); ``` ## Card Templates See `examples/` directory for complete card templates: - `confirmation-card.json` - Confirmation dialogs - `todo-card.json` - Task lists with checkboxes - `poll-card.json` - Polls and surveys - `form-card.json` - Forms with input fields For detailed card design patterns and best practices, see [references/card-design-guide.md](references/card-design-guide.md). ## Callback Handling Callback server automatically sends all card interactions to OpenClaw Gateway. For detailed integration guide, see [references/gateway-integration.md](references/gateway-integration.md). **Quick example:** ```javascript // Handle confirmation if (callback.data.action.value.action === "confirm") { const file = callback.data.action.value.file; // ⚠️ SECURITY: Validate and sanitize file path before use // Use OpenClaw's built-in file operations instead of shell commands const fs = require('fs').promises; const path = require('path'); try { // Validate file path (prevent directory traversal) const safePath = path.resolve(file); if (!safePath.startsWith(process.cwd())) { throw new Error('Invalid file path'); } // Use fs API instead of shell command await fs.unlink(safePath); // Update card await updateCard(callback.context.open_message_id, { header: { title: "Done", template: "green" }, elements: [ { tag: "div", text: { content: `File ${path.basename(safePath)} deleted`, tag: "lark_md" } } ] }); } catch (error) { // Handle error await updateCard(callback.context.open_message_id, { header: { title: "Error", template: "red" }, elements: [ { tag: "div", text: { content: `Failed to delete file: ${error.message}`, tag: "lark_md" } } ] }); } } ``` ## Best Practices ### Card Design - Clear titles and content - Obvious button actions - Use `danger` type for destructive operations - Carry complete state in button `value` to avoid extra queries ### Interaction Flow ``` User request -> Agent decides -> Send card -> User clicks button -> Callback server -> Gateway -> Agent handles -> Update card/execute ``` ### Error Handling - Timeout: Send reminder if user doesn't respond - Duplicate clicks: Built-in deduplication (3s window) - Failures: Update card to show error message ### Performance - Async processing: Quick response, long tasks in background - Batch operations: Combine related actions in one card ## Configuration Configure in `~/.openclaw/openclaw.json`: ```json { "channels": { "feishu": { "accounts": { "main": { "appId": "YOUR_APP_ID", "appSecret": "YOUR_APP_SECRET" } } } }, "gateway": { "enabled": true, "port": 18789, "token": "YOUR_GATEWAY_TOKEN" } } ``` Callback server reads config automatically. ## Troubleshooting **Button clicks not working:** - Check callback server is running - Verify Feishu backend uses "long-polling" mode - Ensure `card.action.trigger` event is subscribed **Gateway not receiving callbacks:** - Start Gateway: `E:\openclaw\workspace\scripts\gateway.cmd` - Check token in `~/.openclaw\openclaw.json` **Card display issues:** - Use provided templates as base - Validate JSON format - Check required fields ## Security **⚠️ CRITICAL: Never pass user input directly to shell commands!** This skill includes comprehensive security guidelines. Please read [references/security-best-practices.md](references/security-best-practices.md) before implementing callback handlers. Key security principles: - Always validate and sanitize user input - Use Node.js built-in APIs instead of shell commands - Implement proper permission checks - Prevent command injection vulnerabilities - Use event_id for deduplication ## References - [Security Best Practices](references/security-best-practices.md) - **READ THIS FIRST!** - [Feishu Card Documentation](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN) - [OpenClaw Docs](https://docs.openclaw.ai)


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)