Feishu Interactive Cards

# 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)